Markdown notes and whiteboards your AI agent can read and write.
Scored across 17 tools
Each tool targets a distinct resource/action (board vs note vs image vs memory), and the plaintext/ciphertext note pairs (create_note/read_note vs create_note_ciphertext/read_note_ciphertext) are clearly differentiated by explicit descriptions. Minor overlap remains between the memory tools and the general note tools since memory is implemented as notes under /memories, but descriptions clarify the boundary.
Strong consistent snake_case verb_noun pattern across nearly all tools: create_note, read_board, update_note, set_access, upload_image, move_item, list_my_notes. The exceptions are memory and memory_view, which are noun-only (mirroring Anthropic's memory tool spec) rather than following the verb_noun convention.
17 tools is on the higher side but justified given the breadth of the surface: notes, boards, an encrypted variant of each, image upload, sharing controls, and agent memory. The plaintext/encrypted duality legitimately doubles several operations, so each tool earns its place.
Notes and boards have create/read/list/move/share coverage, but there is no delete operation for notes, boards, or uploaded images, and boards have no content-update tool (only create/read). Significant lifecycle gaps around deletion and board editing that will leave agents with dead ends.
Creates an Excalidraw whiteboard owned by the signed-in user, optionally seeded with a scene and in a folder, and returns its link. Free plan boards hold up to 300 elements. New boards open to anyone with the link.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Short title (static.md keeps the first 32 characters) | |
| folder | No | Folder to put the whiteboard in, such as "work/launch"; it is made if it doesn't exist yet. A folder the user already has can be given exactly as the list tools show it, spaces included. Default: the top level ("/") | |
| excalidraw_json | No | An Excalidraw scene export ({"elements": [...]}) or an array of Excalidraw elements |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing ownership, return value (the board link), the free-plan element cap, and the important default that new boards open to anyone with the link. These are material behavioral facts an agent would not otherwise know, especially the sharing default, without contradicting the non-destructive/non-idempotent annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the core action and scope. Each sentence adds distinct value: purpose, free-plan limit, and default sharing behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description correctly states that the tool returns the board link. It also covers ownership, optional scene/folder behavior, plan limits, and the default sharing state, leaving no major behavioral gap for an agent calling this creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains title, folder creation, and the accepted Excalidraw scene format. The description mentions optional scene seeding and folder placement but adds no syntax or constraints beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: creates an Excalidraw whiteboard owned by the signed-in user. This clearly distinguishes it from sibling creation tools such as create_note, which produce a different artifact type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it by naming the artifact type and optional seeding/folder behavior, but it never explicitly says 'use this when' or contrasts it with siblings like create_note. An agent can infer the use case, but no exclusions or alternatives are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a markdown note owned by the signed-in user, optionally in a folder, and returns its link. New notes open to anyone with the link, like notes made on static.md; the owner can restrict them in static.md.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Short title (static.md keeps the first 32 characters) | |
| folder | No | Folder to put the note in, such as "work/launch"; it is made if it doesn't exist yet. A folder the user already has can be given exactly as the list tools show it, spaces included. Default: the top level ("/") | |
| markdown | No | Initial markdown content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare the mutation profile (non-read-only, non-idempotent, non-destructive); the description adds genuinely non-obvious behavior — that new notes are link-readable by anyone by default — plus how access is later restricted. That is exactly the kind of consequence an agent could not infer from structured fields. It doesn't cover title truncation effects or authorization requirements, keeping it below 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and its outcome, and the security-relevant default appears immediately after. Slightly compressed by the shared link/site reference, but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, no-output-schema creation tool this covers action, ownership, optional organizational context, return value, and the privacy default. Missing failure behavior (invalid or overly long folder, exceeding 200k markdown) is minor given full schema documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description goes slightly beyond by framing folder as optional and confirming a link is returned, but it adds no syntax or format detail beyond what the schema already documents (max lengths, default '/', folder auto-creation, 32-character title retention).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (creates a markdown note), ownership (signed-in user), optional placement (folder), and return value (link). It implicitly distinguishes itself from create_note_ciphertext by specifying markdown, but never names that sibling, so the differentiation is inferred rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context (notes behave like static.md notes) but no explicit when-to-use or when-not-to-use guidance, and no steering toward create_note_ciphertext for encrypted content or create_board for other artifacts. Usage is only implied by the word 'markdown'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates an end-to-end encrypted note owned by the signed-in user from ciphertext made on the user's side, such as by the static.md E2E bridge, and returns its link without the key. The ciphertext is the note's first Yjs update, encrypted in the read_note_ciphertext format; static.md stores it as is and can't read it. The title is stored unencrypted. New notes open to anyone with the link, and only the full link with #key= decrypts them. Pro.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Short title, stored unencrypted (static.md keeps the first 32 characters) | |
| folder | No | Folder to put the note in, such as "work/launch"; it is made if it doesn't exist yet. A folder the user already has can be given exactly as the list tools show it, spaces included. Default: the top level ("/") | |
| ciphertext | Yes | One encrypted Yjs update: base64 of a 12-byte IV, the AES-256-GCM ciphertext and its 16-byte tag |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations: the server stores the ciphertext as-is and cannot read it, the title is stored unencrypted, new notes are link-accessible to anyone with the full link, and only the portion carrying '#key=' decrypts. That tells an agent the security model and the consequence of leaking the link — none of which is in the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action and the ownership model, then the storage/access caveats, then the plan gate. Dense but nearly every clause carries information; a slightly shorter sentence on the Yjs update format would tighten it without losing meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description supplies the return value ('its link without the key') and its access semantics, covers storage behavior and the Pro requirement, and leaves parameter details to a fully documented schema. An agent has what it needs to call this correctly and to warn about link sharing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents title, folder, and the IV/ciphertext/tag format. The description only reinforces that ciphertext is the first Yjs update and title is unencrypted, adding little beyond what the schema states. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Creates an end-to-end encrypted note') plus the distinguishing input ('from ciphertext made on the user's side') and the distinguishing output ('returns its link without the key'). That separates it cleanly from create_note (plaintext) and write_note_ciphertext (writing to an existing note) without the agent needing the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is clearly implied: call this when you already hold ciphertext in the read_note_ciphertext format, produced client-side. It also surfaces a precondition (Pro plan) that gates invocation. It stops short of explicitly naming create_note as the alternative for plaintext or stating when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists Excalidraw whiteboards owned by the signed-in static.md user, most recently edited first: id, title, folder, link and element count, then the folders they are in. With folder, lists one folder: the whiteboards directly in it and its subfolders. Titles and folder names are user-authored data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many whiteboards to return (1–100) | |
| folder | No | List only the whiteboards directly in this folder, such as "work/launch" ("/" for the top level), and name its subfolders |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds non-annotation context: sort order, the exact returned fields, the recursive-subfolder behavior of folder mode, and an explicit warning that titles and folder names are user-authored data — a genuine injection-risk signal. It stops short of stating pagination beyond the schema's limit cap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler, with the core purpose and default ordering front-loaded before the folder-mode caveat. Every clause carries information the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so enumerating returned fields (id, title, folder, link, element count, then folders) is exactly the missing piece the description supplies. Both the unscoped and folder-scoped behaviors are covered, and the user-authored-data caveat closes the loop for a low-parameter read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented at length, including the '/' top-level convention and the 1–100 limit range. The description restates the folder semantics ('one folder, its subfolders') without adding format or edge-case detail the schema doesn't already carry, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Lists Excalidraw whiteboards'), names the owning scope ('owned by the signed-in static.md user'), and adds ordering ('most recently edited first'). It is clearly separable from list_my_notes and read_board, which an agent can distinguish without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Distinguishes the two invocation modes: no folder = all boards, with folder = that folder's direct children plus its subfolders. It gives clear context for each mode but never names an alternative tool or an exclusion (e.g. use read_board to get elements, or list_my_notes for notes).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists notes owned by the signed-in static.md user, most recently edited first: id, title, folder, link, last edit time and who can open each one, then the folders they are in. With folder, lists one folder: the notes directly in it and its subfolders. Titles and folder names are user-authored data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many notes to return (1–100) | |
| folder | No | List only the notes directly in this folder, such as "work/launch" ("/" for the top level), and name its subfolders |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, non-destructive, closed-world behavior, so the description only needs to add context on top. It adds result ordering, the returned field set, recursion behavior for subfolders, and a useful caveat that titles and folder names are user-authored data. Return format/pagination is not covered, but no output schema exists either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, with the primary behavior and field list front-loaded before the folder variant. The folder behavior is restated in both sentences, slightly redundant but not wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description appropriately enumerates returned fields and ordering, and it covers the folder-scoped variant. An agent still lacks explicit guidance on pagination/truncation beyond limit, which keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters (limit, folder) are already documented in the schema. The description reinforces folder semantics and adds the sort order, but says nothing about limit behavior such as truncation when the cap is hit. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb and resource (lists notes), explicit scope (owned by the signed-in user), explicit ordering (most recently edited first), and an enumerated set of returned fields. It is clearly distinguishable from siblings like read_note or list_my_boards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the two modes of use — no folder means all owned notes, with folder means one folder's direct notes plus its subfolder names — which tells the agent how to choose parameters. It does not name an alternative sibling (e.g. read_note for a single note) or state exclusions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes agent memory, markdown files under /memories, with the writing commands of Anthropic's memory tool; memory_view reads it. Each file is a static.md note in the user's /memories folder: /memories/projects/static-md.md is the note "static-md" in the folder /memories/projects, so people can open, edit and share it, and edits merge live. create writes a file, replacing the text of one that exists. str_replace replaces old_str, which must occur exactly once, with new_str. insert puts insert_text after line insert_line (0 for the top). delete removes a file, or a directory with everything in it. rename moves a file or directory from old_path to new_path. File names: up to 32 characters before ".md", of letters A-Z, digits, "-", "_" and "."; directories up to 9 levels. Encrypted notes are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | The file or directory, under /memories (e.g. "/memories/projects/static-md.md"). Every command but rename | |
| command | Yes | What to change; view is memory_view | |
| new_str | No | str_replace: the replacement (empty or left out deletes old_str) | |
| old_str | No | str_replace: the text to replace, exactly as in the file | |
| new_path | No | rename: where it goes | |
| old_path | No | rename: the file or directory to move | |
| file_text | No | create: the whole file | |
| insert_line | No | insert: the line to insert after; 0 is the top of the file | |
| insert_text | No | insert: the text to insert |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds real context beyond the destructiveHint=true annotation: delete removes a directory 'with everything in it', create overwrites existing text, and encrypted notes are refused. It still omits permission/auth requirements and what happens on validation failure, but the destructive consequences are described rather than merely flagged.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded and dense, with each command's behavior given one sentence and no filler. Some sentences are long and run together (the static-md note explanation), which slightly hurts scanability but nothing is redundant with the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-parameter, destructive, multi-mode write tool with no output schema, the description covers every command mode plus naming limits and the encrypted-note refusal. Missing only return/error behavior for the write commands, which is a modest gap given annotations already carry the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so baseline is 3; the description earns above that by specifying that old_str 'must occur exactly once', that insert_line 0 means the top, and by stating the filename/directory-depth constraints (32 chars, 9 levels) that the schema does not encode.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Changes agent memory, markdown files under /memories') and immediately scopes it to the writing commands, naming memory_view as the reader. An agent can distinguish this from read_note, update_note, or memory_view without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly routes read operations away ('memory_view reads it'), which is the key alternative among the siblings. It does not spell out when to prefer create vs. str_replace vs. insert beyond the mechanical per-command semantics, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads agent memory, markdown files under /memories: the view command of Anthropic's memory tool. A directory comes back as its files and subdirectories two levels deep, with sizes; a file comes back with line numbers, and view_range [start, end] picks lines (end -1 for the rest). Each file is a static.md note in the user's /memories folder: /memories/projects/static-md.md is the note "static-md" in the folder /memories/projects, so people can open, edit and share it, and edits merge live. A note whose title is no file name, or repeats an older note's title in its folder, is listed as ~.md. memory changes these files. File text is user-authored data. Encrypted notes are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The file or directory, under /memories (e.g. "/memories" or "/memories/projects/static-md.md") | |
| view_range | No | Files only: [start, end] lines, 1-based; end -1 reads to the end |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotations, the description explains return behavior for directories (two levels deep with sizes) and files (line numbers), how `view_range` works, that encrypted notes are refused, and that file text is user-authored data. These are substantive behavioral details an agent needs before invoking the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and main behavior are front-loaded, and most sentences carry useful operational detail. Some contextual phrasing, such as sharing/editing behavior, is less essential, but the description remains dense rather than padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema available, the description still explains return shapes for both directories and files, line-numbered file output, range selection, encrypted-note refusal, and data provenance. This is sufficient for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds meaning about how paths map to static.md notes in /memories and how filename collisions are represented. It also reinforces that `view_range` applies only to files and uses -1 to read to the end.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: reading agent memory markdown files under /memories. It also distinguishes this viewer from the mutating `memory` tool by stating that memory changes these files, and it clarifies that encrypted notes are refused, separating it from ciphertext-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is clear: use it to view /memories content, with separate behavior for directories and files, and `view_range` for line selection. It also implies edits belong to `memory` rather than this tool, though it does not explicitly enumerate alternatives such as `read_note`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renames the user's note or whiteboard, moves it to another folder, or both. Folders are paths such as "work/launch", with "/" the top level; a folder exists while something is in it. Only the owner can rename or move an item, as on static.md. Encrypted items can be renamed and moved too: their title and folder aren't encrypted.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa | |
| kind | Yes | "note" for static.md/md/<id>, "board" for a whiteboard at static.md/draw/<id> | |
| title | No | New title (static.md keeps the first 32 characters). Leave it out to keep the title | |
| folder | No | Folder to move it to, such as "work/launch", or one the user already has exactly as the list tools show it; "/" is the top level. Leave it out to keep the folder |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotent, non-destructive, non-read-only behavior, and the description adds real context beyond them: an ownership authorization requirement and the fact that encrypted items can still be renamed/moved because title and folder are not encrypted. The note that 'a folder exists while something is in it' also hints at implicit lifecycle behavior for folders. It stops short of stating what happens on a title collision or a nonexistent folder path.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the primary action, then folder semantics, then permission and encryption caveats. Each sentence carries a distinct fact with no padding, though the folder-path sentence slightly duplicates the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description covers the decision-critical facts an agent needs: owner-only authorization, encrypted-item eligibility, and folder path conventions. It could be stronger by stating whether a move into a new path auto-creates folders or fails, but nothing essential is missing for a 4-parameter mutation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so id, kind, title, and folder are already fully documented, including the pattern, enum, maxLength, and the 'leave it out to keep' semantics. The description's folder-path explanation ('work/launch', '/' as top level) largely restates the schema and adds no new syntax or constraint detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb pair (rename, move) and the resources it acts on (note, whiteboard), and covers the 'both at once' case explicitly. This is clearly distinguishable from siblings like create_note, update_note, and write_note_ciphertext, which address content rather than title/location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives useful preconditions ('Only the owner can rename or move an item') and clarifies that encrypted items are still eligible, which helps an agent decide it can call this at all. However, it never contrasts with update_note or explains when to prefer this over other mutation paths, so alternative selection is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a static.md Excalidraw whiteboard the user can open: element count, element types, the text on the board, and the scene JSON (when under 300 KB). Board text is written by users and comes back marked as untrusted data. Encrypted boards are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial context beyond the annotations: the 300 KB cap on returning scene JSON, the fact that user-authored board text is returned marked as untrusted data, and that encrypted boards are rejected. It does not say what happens above the size cap (truncation vs. omission), which is the one behavior an agent might trip on.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the return payload, then size constraint, then security and refusal notes. No filler and no repetition of name or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description enumerates the returned fields (element count, element types, board text, scene JSON) plus the size condition. For a single-parameter read tool nothing an agent needs in order to call it is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter and schema coverage is 100%, with the pattern and link-suffix example already documented in the schema. The description adds nothing about the id, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (returns) and resource (a static.md Excalidraw whiteboard), then enumerates exactly what comes back. The whiteboard framing plus sibling names like read_note and create_board make the resource distinction unambiguous without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the id-based read of a board, and 'Encrypted boards are refused' supplies one real exclusion. However, it never explicitly routes the agent between this and read_note/read_note_ciphertext, or says what to do when a board is encrypted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the markdown of a static.md note the user can open, with the notes its [[wikilinks]] lead to and the notes linking to it. The note is written by users and comes back marked as untrusted data. Encrypted notes are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and non-destructive annotations, it discloses meaningful behavior: the return includes linked and backlinked notes, user-authored content is marked as untrusted data, and encrypted notes are rejected. These are important operational details an agent would not get from the annotations alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the return value and followed by important behavioral constraints. Every sentence adds useful information without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description carries the return-value burden, and it does so well by explaining the markdown content, wikilink graph, untrusted marking, and encrypted-note refusal. An agent has enough context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the id parameter is fully documented with a pattern and example link. The description does not add further semantics about the id beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it returns the markdown of a static.md note. It also clarifies that the result includes outgoing wikilink notes and backlinks, and that encrypted notes are refused, which distinguishes it from read_note_ciphertext.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context by specifying that the note is one the user can open and that encrypted notes are refused. However, it does not explicitly name read_note_ciphertext as the alternative for encrypted notes, so the routing relies on inference from the sibling tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the ciphertext of an end-to-end encrypted static.md note, for a program on the user's side that holds the key, such as the static.md E2E bridge. static.md has no key and can't decrypt it. The answer is JSON (format static.md/e2e-note/v1) listing the note's encrypted Yjs updates, each base64 of a 12-byte IV, the AES-256-GCM ciphertext and its 16-byte tag. Pro.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish that this is a safe, read-only, closed-world operation, so the description does not need to restate safety. It adds meaningful behavior beyond the annotations: static.md has no key and cannot decrypt the note, and the response is a specific JSON format with encrypted Yjs updates, base64 IVs, AES-256-GCM ciphertext, and tags.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is front-loaded and mostly tight, covering purpose, caller constraint, and response format in three sentences. The trailing 'Pro.' is unexplained and adds no value, which slightly hurts an otherwise efficient description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description thoroughly explains the return payload: JSON in static.md/e2e-note/v1 format with encrypted Yjs updates containing base64-encoded IV, AES-256-GCM ciphertext, and tag. An agent has enough information to call this correctly and understand what comes back.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single id parameter is already well documented with its pattern and link-derived example. The description adds no further parameter syntax or semantics, which is an acceptable baseline when the schema carries this burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a precise verb-and-resource framing: it returns the ciphertext of an end-to-end encrypted static.md note. It clearly distinguishes itself from the sibling read_note by emphasizing ciphertext and encryption, and it states up front that static.md cannot decrypt the content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains the intended caller: a program on the user's side that holds the key, such as the E2E bridge. That gives a clear context for use and implicitly routes plaintext-reading needs elsewhere, but it never explicitly names read_note or states when not to call this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Pro: searches the titles and text of the signed-in user's static.md notes, and of notes shared with them, for words or "quoted phrases". Every word must appear; case and accents are ignored. Returns the best matches first: id, title, folder, link, last edit time and a short snippet around the hit. End-to-end encrypted notes match on their title only. With folder, searches the user's own notes in that folder and its subfolders. Titles and snippets are user-authored data.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many matches to return (1–50) | |
| query | Yes | Words to find, such as launch budget; a phrase in double quotes ("launch plan") matches as written | |
| folder | No | Search only the user's notes in this folder and its subfolders, such as "work/launch"; "/" is all of them. A folder the user already has can be given exactly as the list tools show it, spaces included |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real behavioral detail on top: ranking ("best matches first"), the exact fields returned, snippet generation around the hit, and the encryption-driven limitation on what can be matched. The trailing note that titles and snippets are user-authored data is a meaningful trust/instruction-injection warning.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Content is front-loaded with scope and query semantics before return shape, and nearly every sentence carries information. Minor redundancy exists between "With folder, searches the user's own notes in that folder and its subfolders" and the folder parameter's own schema description, which already states the same recursion behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description compensates by listing the returned fields and the ranking/ordering behavior. Combined with the query-matching rules and the encrypted-notes caveat, an agent has everything needed to call this correctly and interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns extra by explaining query semantics the schema only partly covers (all words must appear, quoted phrases match verbatim, case and accents ignored) and by clarifying that folder search recurses into subfolders. The limit parameter is left entirely to the schema, which is acceptable given its explicit range and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb (searches) plus the exact resource and scope: titles and text of the signed-in user's notes plus notes shared with them. It also names the corpus boundary that matters (end-to-end encrypted notes match on title only), which separates it from read_note and list_my_notes without needing to name those siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states clearly what the tool searches and how matching behaves (every word must appear, quoted phrases match as written, case/accents ignored), which tells an agent when this is the right call. It does not explicitly say when to prefer list_my_notes browsing or read_note retrieval instead, so the routing guidance is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes who can open the user's note or whiteboard. access "public": anyone with the link; "only_me": just the owner; "emails": the owner plus the listed readers, and editors can also edit (the lists replace the current ones). Only the owner can change it. "only_me" and "emails" are Pro features; encrypted items can't be shared by email; up to 50 people.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa | |
| kind | Yes | "note" for static.md/md/<id>, "board" for a whiteboard at static.md/draw/<id> | |
| access | Yes | Who can open it | |
| editors | No | With "emails": email addresses of people who can also edit it (they can open it too) | |
| readers | No | With "emails": email addresses of people who can open it |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, idempotentHint=true), the description supplies the crucial behavioral fact that editors/readers lists REPLACE the current ones, plus authorization requirements, Pro-tier gating, encryption restrictions, and the 50-person limit. That is exactly the context an agent needs before invoking a destructive, idempotent mutation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense and front-loaded, leading with the operation and then enumerating access modes in order of restrictiveness. The quoted-key shorthand ("access "public": ...") is terse to the point of being slightly cryptic, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers authorization, tier limits, encryption constraints, and the replacement semantics that a mutation tool most needs, and no output schema exists so return values needn't be described. The one real gap is the conditional requirement of editors/readers for the "emails" mode, and no mention of what failure looks like.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns above baseline by explaining what each access value actually means ("public" = anyone with the link, "emails" = owner plus listed readers, editors can also edit) and that the lists overwrite existing entries. It does not say whether readers/editors are required when access="emails".
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("changes who can open the user's note or whiteboard") and scopes it to the owner's own items. It does not, however, differentiate itself from the sibling set_read_only, which an agent could plausibly confuse with this permission-modeling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear preconditions: only the owner can change access, "only_me"/"emails" are Pro features, encrypted items can't be shared by email, and lists cap at 50 people. It never explicitly says when to prefer this over set_read_only, so the routing guidance is implicit rather than complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turns read-only on or off for the user's note or whiteboard. While it is on, only the owner can change the content, and everyone who can open it can still read it (set_access decides who that is). Only the owner can change it. Turning it on is a Pro feature.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa | |
| kind | Yes | "note" for static.md/md/<id>, "board" for a whiteboard at static.md/draw/<id> | |
| read_only | Yes | true: only the owner can edit it; false: everyone who can edit it today can again |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond the annotations by disclosing the permission model (only the owner can change content or the setting, readers retain read access) and a real precondition — turning it on requires Pro. That explains why destructiveHint=true is set: enabling it removes editing ability from collaborators. It doesn't state what happens on a Pro-gated failure or whether disabling restores prior per-user permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the core action in the first sentence and keeps the whole thing to four short sentences. The clause 'Only the owner can change it' largely repeats the preceding sentence about owner-only editing, leaving mild ambiguity about whether it refers to content or to the setting itself.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter mutation with no output schema, the description supplies the essentials: permission model, effect on readers, the Pro requirement, and the sibling that governs visibility. Minor gaps remain around failure behavior when not Pro and whether note and board differ in any way.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the schema already explains id format, the note/board enum, and the boolean semantics precisely. The description adds no parameter-level detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource+scope: toggling read-only on a user's note or whiteboard. It also separates the concern from set_access (which decides who can open it), so an agent can distinguish it from the access-control sibling without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly frames the operation as a toggle ('on or off') and points to set_access for the separate question of who can open the item, which is the main routing ambiguity among siblings. It stops short of explicit when-not-to-use guidance (e.g., when the item is already in the desired state or when the caller isn't the owner).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Changes a note's markdown. mode "append" adds text on a new line at the end; mode "replace" makes the note exactly the given markdown. Edits merge live with people typing in the note. Needs edit access; encrypted notes are refused.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa | |
| mode | Yes | "append" adds to the end; "replace" overwrites the whole note | |
| markdown | Yes | Markdown to append, or the complete new note for "replace" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructive/non-idempotent/not-read-only, and the description adds substantially beyond that: edits merge live with concurrent typers, edit access is required, and encrypted notes are refused. These are exactly the behavioral traits an agent must know before calling a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, zero filler, and the core action and mode semantics are front-loaded ahead of the access/encryption caveats. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a three-parameter mutation tool with annotations covering the safety profile and no output schema, the description covers action, mode semantics, concurrency behavior, and preconditions. Nothing an agent needs in order to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents id, markdown and mode. The description's mode explanation ('adds text on a new line at the end') adds a small amount of detail beyond the schema's 'adds to the end', but it largely restates what the schema provides, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Changes a note's markdown') and immediately defines the two operating modes, which is enough to separate it from read_note and create_note. The scope is pinned down without the agent needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what each mode does and the preconditions (edit access, encrypted notes refused), which implies when it is usable. However, it never states when to choose update_note over create_note or read_note, nor any when-not-to-use guidance, so the routing signal is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Uploads an image, such as a screenshot, chart or diagram, to static.md image hosting and returns its link, a markdown snippet that embeds it in a note (), and its type, size in bytes and dimensions. Takes JPG, PNG, GIF, WebP, AVIF, HEIC, SVG, BMP or ICO up to 10 MB, as base64 or a data: URL; HEIC is stored as JPEG. Anyone with the link can open the image, and it is listed in the user's uploads on static.md. The same image always gets the same link.
| Name | Required | Description | Default |
|---|---|---|---|
| alt | No | Alt text for the markdown snippet: what the image shows. Default: the file name | |
| data | Yes | The image file as base64, or as a data: URL such as "data:image/png;base64,iVBORw0…". An SVG can also be a URL-encoded "data:image/svg+xml,<svg …>" | |
| filename | No | Name for the file in the user's uploads, such as "revenue-q3.png" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations: it discloses the 10 MB cap, the accepted formats, HEIC-to-JPEG conversion, that the image is publicly readable by anyone with the link, that it appears in the user's uploads, and that identical images dedupe to the same link (reinforcing idempotentHint). The public-visibility warning is exactly the kind of side effect an agent needs before calling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with zero filler: purpose and return values first, then input constraints, then the privacy and idempotency properties. Nothing is repeated from the name or title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing the full return payload (link, markdown snippet, type, bytes, dimensions). For a single-shot upload with no dependencies, the format limits, privacy disclosure and dedupe behavior cover everything an agent needs to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3; the description still adds value by specifying the 10 MB envelope and the accepted format set, which constrain what may legitimately be passed in `data`. The alt-text default and filename semantics are left to the schema, so it does not fully supersede it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Uploads an image ... to static.md image hosting') and enumerates exactly what comes back: link, markdown snippet, type, size and dimensions. The resource is plainly distinct from every sibling (boards, notes, ciphertext), so an agent can route to it without inspecting other schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is clearly implied by the return contract — the markdown snippet 'that embeds it in a note' tells the agent this is the tool to reach for when a note needs an image. It stops short of explicitly naming alternatives or exclusions (e.g. 'do not use for text attachments'), so it is strong context rather than full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Adds one encrypted Yjs update, made on the user's side in the read_note_ciphertext format, to an end-to-end encrypted note: the change from an edit, which merges live with people typing in the note. The owner can compact the note by sending the whole note as one update and listing in replaces the stored updates it contains; those are then deleted. Needs edit access. Pro.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id at the end of the link, e.g. "k3v9qa" in https://static.md/md/k3v9qa | |
| replaces | No | Owner only: refs (from read_note_ciphertext) of the stored updates this update contains in full, to delete once it is stored | |
| ciphertext | Yes | One encrypted Yjs update: base64 of a 12-byte IV, the AES-256-GCM ciphertext and its 16-byte tag |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag destructiveHint=true and idempotentHint=false, and the description earns credit on top by explaining *what* is destroyed (stored updates listed in replaces are deleted after the write) and the merge-not-overwrite semantics. It also discloses the edit-access and Pro-plan requirements. Missing only failure/conflict behavior when a merge is rejected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core action is front-loaded, but it is delivered as one dense run-on sentence, and the clause 'listing in replaces the stored updates it contains' is grammatically tangled enough to slow comprehension. No filler, but readability costs it a point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, an agent can still act correctly: annotations cover the safety profile and the description covers auth, tier, merge semantics, and the compaction path. The only gap is that it never says what a successful write returns or how a ref for later replaces is obtained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description adds value by clarifying that ciphertext is produced client-side in the read_note_ciphertext format and that replaces is an owner-only compaction mechanism. It doesn't add detail on the id format or size limits, but those are already well covered in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: adds one encrypted Yjs update to an end-to-end encrypted note. It also pins the payload format by referencing the sibling read_note_ciphertext, which separates it from the plaintext update_note and from create_note_ciphertext. It never explicitly contrasts itself with those siblings, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives real usage context: the update merges live with concurrent editors, and the compaction path (send the whole note as one update plus replaces) is spelled out for owners. Prerequisites are named ('Needs edit access. Pro.'). It stops short of saying when to use this versus update_note or create_note_ciphertext.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
memorymemory_viewsearch_notescreate_board1 field changedInput schema / properties / folder / descriptionPrevious value: -"Folder to put the whiteboard in, such as \"work/launch\"; it is made if it doesn't exist yet. Default: the top level (\"/\")"New value: +"Folder to put the whiteboard in, such as \"work/launch\"; it is made if it doesn't exist yet. A folder the user already has can be given exactly as the list tools show it, spaces included. Default: the top level (\"/\")"create_note1 field changedInput schema / properties / folder / descriptionPrevious value: -"Folder to put the note in, such as \"work/launch\"; it is made if it doesn't exist yet. Default: the top level (\"/\")"New value: +"Folder to put the note in, such as \"work/launch\"; it is made if it doesn't exist yet. A folder the user already has can be given exactly as the list tools show it, spaces included. Default: the top level (\"/\")"create_note_ciphertext1 field changedInput schema / properties / folder / descriptionPrevious value: -"Folder to put the note in, such as \"work/launch\"; it is made if it doesn't exist yet. Default: the top level (\"/\")"New value: +"Folder to put the note in, such as \"work/launch\"; it is made if it doesn't exist yet. A folder the user already has can be given exactly as the list tools show it, spaces included. Default: the top level (\"/\")"move_item1 field changedInput schema / properties / folder / descriptionPrevious value: -"Folder to move it to, such as \"work/launch\"; \"/\" is the top level. Leave it out to keep the folder"New value: +"Folder to move it to, such as \"work/launch\", or one the user already has exactly as the list tools show it; \"/\" is the top level. Leave it out to keep the folder"upload_imagecreate_board1 field changedInput schema / properties / folderAdded value: +{
+ "description": "Folder to put the whiteboard in, such as \"work/launch\"; it is made if it doesn't exist yet. Default: the top level (\"/\")",
+ "maxLength": 700,
+ "type": "string"
+}create_note1 field changedInput schema / properties / folderAdded value: +{
+ "description": "Folder to put the note in, such as \"work/launch\"; it is made if it doesn't exist yet. Default: the top level (\"/\")",
+ "maxLength": 700,
+ "type": "string"
+}create_note_ciphertext1 field changedInput schema / properties / folderAdded value: +{
+ "description": "Folder to put the note in, such as \"work/launch\"; it is made if it doesn't exist yet. Default: the top level (\"/\")",
+ "maxLength": 700,
+ "type": "string"
+}list_my_boards1 field changedInput schema / properties / folderAdded value: +{
+ "description": "List only the whiteboards directly in this folder, such as \"work/launch\" (\"/\" for the top level), and name its subfolders",
+ "maxLength": 700,
+ "type": "string"
+}list_my_notes1 field changedInput schema / properties / folderAdded value: +{
+ "description": "List only the notes directly in this folder, such as \"work/launch\" (\"/\" for the top level), and name its subfolders",
+ "maxLength": 700,
+ "type": "string"
+}move_itemcreate_note_ciphertextread_note_ciphertextwrite_note_ciphertextset_read_onlycreate_boardcreate_notelist_my_boardslist_my_notesread_boardread_noteset_accessupdate_noteMarkdown workspace for AI agents: read, write, organize, and share markdown documents.
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Markdown notes in folders, with files, that your AI assistant can read, write and organise.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Add one secure layer between your agents and this server.
