Endpoint notes

An endpoint note is a short fact about one SmartZone API endpoint that your organisation learned by calling it, such as a filter the controller refuses or a body shape that differs from the spec. Once saved, every member of your organisation sees it whenever Claude looks that endpoint up. Claude saves and removes notes with save_endpoint_note and remove_endpoint_note, on both wifi and switches. There is no dashboard page for them: they are managed through Claude only.

When does Claude save a note?

Claude saves one when a call proves something about an endpoint that its spec, its curated caveats and the SmartZone guides don’t say: a refused filter, a body or response shape that differs, an error that means something else. Claude is told to use notes sparingly, to keep them to facts with no names or addresses from your network, and to tell you when it saves one. You can also simply ask: “save a note on POST /query/ap that …”.

Who sees a note?

A note has one of two scopes:

Scope	Who sees it	Author shown
org	Every member of the organisation that saved it. Every note starts here	Yes, as by (the author’s sign-in email), to your own organisation
global	Every organisation on SZ-MCP	No

Only an SZ-MCP site administrator (NeuralConfig) can make a note global, take it back to org, or delete a global note. A global note outlives the organisation that wrote it. Deleting an organisation deletes its own org notes.

Where do notes show up?

Notes appear in two places:

Where	What you see
get_endpoint_details	A notes array: [{ id, scope, note, by?, at }], your organisation’s notes first, then global ones, newest first within each
search_endpoints and list_endpoints_by_tag hits	notesCount: how many notes you can see on that endpoint, present only when there is at least one

Notes sit beside the curated caveats, which are quirks verified on a live controller and shipped with SZ-MCP. Caveats override the spec; notes are your organisation’s own record.

Saving a note

save_endpoint_note takes the endpoint and the text:

Argument	Notes
method	Required. GET, POST, PUT, PATCH or DELETE
path	Required. The spec path, starting /. A path with values filled in is matched to its spec template, and the note is stored on the template
note	Required. 5–500 characters after trimming

await wifi.save_endpoint_note({ method: 'POST', path: '/query/ap', note: 'Returns 400 when STATUS is in filters; filter on the returned status field.' });

It returns { ok: true, id, scope: 'org' }. The operator role or above can save notes; a viewer is refused.

Removing a note

remove_endpoint_note({ id }) takes the id from notes. You can remove your own notes; an organisation admin or owner can remove any of the organisation’s notes. It returns { ok: true }.

Limits and errors

Limit	Value	On reaching it
Note length	5–500 characters	note_too_short or note_too_long, with limit. Over 1,000 characters is refused by the call’s argument check first
Notes on one endpoint	10 per organisation	too_many_notes_for_endpoint
Notes in total	500 per organisation	too_many_notes

Notes have no expiry; they stay until someone removes them. Every refusal below comes back as { ok: false, error, … }:

error	From	Meaning
write_blocked	save	Your role is viewer: “Your role in this organisation (viewer) can read endpoint notes but not save them; an operator, engineer or admin can.”
endpoint_not_found	save	No such method and path in the bundled API index
note_too_short, note_too_long	save	Under 5, or 501 to 1,000, characters after trimming
too_many_notes_for_endpoint, too_many_notes	save	A limit above
not_found	remove	”No note with this id in this organisation.”
not_author	remove	”Only its author or an org admin can remove this note.”
global	remove	”This note is shared with every organisation; only the site admin can remove it.”

Next steps

Finding the right endpoint The discovery path where notes and caveats show up.

Searching the SmartZone guides Check the vendor guides before saving a note.

Code mode primitives The full reference for get_endpoint_details and the note primitives.