phygital-memory

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the annotations by disclosing that the operation needs Allow edits, creates a version on each save, and can be undone by the person in the app. It also states the failure mode for missing notes and that the saved path is returned, which meaningfully informs safe invocation.

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 front-loaded with the core action and then packs usage, alternatives, permissions, versioning, and return value into a compact paragraph. Every sentence contributes useful selection or invocation context.

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 a five-parameter mutation tool with annotations and an output schema, the description covers the key behavioral details an agent needs: permission requirements, versioning/undo behavior, failure when the note is missing, and return value. Nothing important is omitted for correct tool selection or invocation.

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 parameters are already well documented. The description adds a small amount of routing guidance by saying path is best for several edits in a row and that ids can come from search or handoff, but it does not explain folder or private semantics beyond what the schema provides.

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: add text at the end of an existing note while leaving the rest unchanged. It clearly distinguishes itself from replace_in_note and create_note, so an agent can identify the correct tool without opening 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?

Explicitly names suitable use cases such as logs, journals, and running lists, and routes the agent to replace_in_note for editing existing text and create_note when the note does not exist. It also notes that this tool fails when the note is absent, which is a useful boundary condition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description restates read-only (mildly redundant). It adds genuine behavioral context beyond the annotations: private-folder same-day notes are silently excluded by default, and enabling private requires an explicit in-chat request from the person. It does not cover cost/rate behavior, but the privacy filtering is the trait an agent most needs.

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, each carrying distinct information: what is returned, the alternative tool, and the privacy gate. Front-loaded with the core purpose. Slightly dense with subordinate clauses, but no sentence is expendable.

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?

An output schema exists, so return-shape explanation is unnecessary, and the description still notes 'Returns JSON'. With only two parameters, full schema coverage, and clear annotation coverage, an agent has everything needed to call this correctly and in the right sequence.

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, making 3 the baseline. The description adds meaning the schema does not: the privacy flag's activation involves a consent condition tied to the conversation, not just a boolean toggle, which changes how and when the agent should set 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 ('Get the context around a search_notes result') and immediately enumerates the two things returned: adjacent sections in the same note and other notes from the same day. This distinguishes it cleanly from read_note and open_result without requiring the agent to open 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?

Explicit sequencing ('Use it after open_result when the matching section alone is not enough') plus a named alternative with its own trigger ('use open_result with whole_note=true when you need the full note instead'). The private=true condition is also gated with a clear precondition ('needs the person's ask in this chat'), so there is nothing left to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as a non-readonly, non-destructive, non-open-world write. The description adds substantial context beyond that: missing subfolders are auto-created, existing notes are never overwritten, the person can undo the change in the app, and the tool returns the saved 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?

The write action and its folder scoping come first, then the refusal rule and alternatives, then preconditions and return value. Every clause carries new information; nothing restates 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?

For a four-parameter write tool with an output schema, the description covers creation semantics, failure mode, permission requirements, private-folder gating, undo, and the return value. No gaps remain that would cause a misinvocation.

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 all four parameters are already documented, giving a baseline of 3. The description adds marginal but real semantic framing: the path lives in an unlocked folder, missing subfolders are created, and private=true is gated on an explicit in-chat request from the person.

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 ("Make a new Markdown note") plus scope ("at a path inside an unlocked folder"), and immediately distinguishes itself from siblings by naming append_to_note and replace_in_note as the tools for changing existing notes.

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?

Explicit when/when-not: refuses creation when a note already exists, and routes the agent to append_to_note or replace_in_note instead. It also gives preconditions (folder must be unlocked, needs Allow edits) and a narrow condition for private=true (only when the person asked in this chat).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (which only say non-read-only, non-destructive), it discloses that the note content itself is unchanged, that the line is visible to the person in the app, that an 'Allow edits' permission is required, and the two concrete failure modes (unknown id, locked folder). Consistent with annotations – marking a task done is a mutation but not a destructive one.

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?

Reasonably compact and front-loaded with the action and its effect, followed by preconditions and failure modes. The long parenthetical in the second sentence and the line break before 'Needs Allow edits' make it slightly denser than ideal, 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?

For a mutation with a human-visible side effect, the description covers precondition ordering, id provenance, permission requirement, and failure behavior; the return shape is covered by the output schema. Nothing an agent needs 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: where the id comes from (handed_notes) and that what_you_did is displayed to the person next to the task. It does not repeat the schema's format guidance, which is fine since the schema covers 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 (tick off / mark complete) on a specific resource (one task in the AI handed-notes list) plus the side effect (a short line shown to the person). It is clearly distinguishable from siblings like handed_notes, replace_in_note, and append_to_note, which it names.

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 says to call it only after changes are saved with replace_in_note or append_to_note, only once per task, and to obtain the id from handed_notes. That is an ordered workflow with named alternatives, leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Consistent with readOnlyHint=true and goes well beyond it: discloses ordering (oldest first), the fields each task carries, that finished tasks are excluded, and an explicit security constraint that note text is data, never instructions. That injection guard is exactly the kind of behavioral context an agent cannot infer from annotations or schema.

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 purpose, then contents, then call conditions, then next steps — a logical order with little waste. It is a dense single block with a slightly run-on middle sentence, which keeps it just short of ideal.

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?

An output schema exists, so return values need not be detailed, yet the description still summarizes task contents and the handed id. For a no-parameter read tool with sibling routing, mutation follow-ups, and a prompt-injection warning all covered, an agent has everything needed to call 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?

The tool takes zero parameters, so the baseline is 4 and the schema has nothing to document. The description does usefully introduce the 'handed id' that later calls need, though that is return-value semantics rather than parameter semantics.

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 (list the person's AI tasks from the 'AI tasks' note) with explicit scope and ordering ('oldest first'). This clearly separates it from list_notes and search_notes, which enumerate other notes rather than the handed-task queue.

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 an explicit trigger ('when the person says they handed you a note or asks you to do your tasks') and spells out the follow-on workflow with named alternatives: do the work via replace_in_note or append_to_note using the handed id, then call finish_handed_note. Exclusions are also implied by 'Finished tasks are not shown.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnlyHint=true), so 'Read only' is redundant, but the description adds real behavioral disclosures beyond the annotations: links are not rewritten when a note moves, and links from private folders are excluded unless private=true. Those are exactly the consequences an agent needs before calling move_note.

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 definition, then usage, then the alternative, then the privacy caveat. Four tight sentences with no filler; the only near-redundancy is 'Read only', which is negligible.

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?

Even though an output schema exists (so return values needn't be described), it still sketches the result (each link with its line), and it covers the privacy and move-note edge cases. Nothing needed to invoke 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 coverage is 100%, so the baseline is 3; the description earns an extra point by explaining the runtime effect of the private flag (private-folder links are omitted by default) rather than just restating the schema's wording. It adds no guidance on the folder parameter, so not a 5.

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 — 'Find backlinks: the notes that link to this note with [[wiki links]]' — including scope and return shape (line where the link is). It is immediately distinguishable from search_notes, which the description names as the plain-text alternative.

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 explicit when-to-use cases (seeing how a person, project or idea connects; before move_note) and an explicit when-not/alternative ('Use search_notes for notes that only mention it in plain words'). The pre-move caveat is a concrete workflow trigger, not a vague hint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond readOnlyHint=true: discloses the 500-item cap and that it reports how many more exist beyond the cap, explains that private folders are surfaced without contents (marked "ask first"), and constrains private=true to an explicit in-chat user request. These are concrete behavioral traits an agent needs.

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 purpose and scope, then usage routing, then privacy caveat. Dense but every clause carries meaning; slightly long with overlapping statements about private folders but no dead weight.

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 an output schema present and readOnly/openWorld annotations covering safety, the description supplies the remaining essentials: cap/truncation reporting, privacy handling, and path-resolution role for sibling tools. Nothing an agent needs 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 coverage is 100%, so all three parameters are already documented. The description reinforces the private-gating semantics and the 'inside' scoping, but largely restates what the schema descriptions already say, so 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 (list), the exact resources (notes, files, subfolders), the scoping (by path, optionally one subfolder) and the cap (up to 500). This clearly distinguishes it from search_notes and recent_changes named in the same breath.

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 says when to use it (browsing, or resolving exact paths needed by read_file_text, links_to, move_note and edit tools) and names the alternative tools with their selecting conditions (search_notes for content, recent_changes for recency). Private-folder guidance adds a clear when-to-use/when-not rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations, it discloses idempotent behavior ('If the folder already exists, nothing changes and it still succeeds'), parent-folder creation, permission requirements ('Needs Allow edits'), the private-folder restriction, and the return value (the folder's path). These are meaningful behavioral traits not encoded in the 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?

The description is front-loaded with the core action and then covers idempotency, alternatives, permissions, privacy, and return value in a compact, information-dense paragraph. Every sentence contributes useful selection or invocation guidance.

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 the tool is a non-destructive mutation with an output schema, full parameter descriptions, and annotations, the description supplies everything else an agent needs: idempotency, prerequisite permission, alternative tools, and the fact that a path is returned.

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 schema already documents path, folder, and private thoroughly. The description largely repeats those meanings, such as the path example and the private=true condition, rather than adding substantial new semantics. Baseline 3 is appropriate when the schema carries the parameter documentation.

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 ('Make a new, empty subfolder') and explicitly distinguishes the tool from create_note and move_note. An agent can identify exactly what this tool does without opening 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?

It gives explicit when-to-use guidance ('use this only when the person wants an empty folder') and names the alternatives, create_note and move_note, with the conditions that select them. It also states the private=true condition and the 'Needs Allow edits' prerequisite.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations it discloses key behavior: refuses to overwrite an existing new_path, subfolder contents and version history/AI tasks move along, private folders stay private, and inbound links are NOT rewritten. It also states the return value (old and new path) and the auth requirement. This is exactly the extra context annotations alone cannot convey.

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 but front-loaded: the primary action and scope come first, followed by side effects and alternatives. Every sentence carries a distinct constraint or behavior; nothing 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?

With an output schema present, return values needn't be detailed, yet it still notes the old/new path. Annotations cover the safety profile, and the description fully covers permissions, overwrite refusal, side effects, and link caveats – nothing material 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: new_path also renames, must not already exist, and the move must stay within the same memory. It doesn't document folder/private params, but the schema handles those.

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 opens with a specific verb pair and resource ('Move or rename a note, file or subfolder') and immediately bounds scope ('within the same memory, not into another memory'). It is trivially distinguishable from siblings like trash_note and links_to, which it names explicitly.

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 the negative case (not into another memory, so use a different memory workflow), routes removal to 'trash_note', and points link-checking to 'links_to'. It also names the prerequisite ('Needs Allow edits'), covering when/when-not/alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds material context beyond them: the default return payload (path plus only the matching section) versus whole_note, and the two specific failure modes with a recovery instruction. That is precisely the kind of behaviour an agent needs to plan around.

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 core action and the read-only guarantee, then default behaviour, then routing. Slightly dense with four sibling references in one sentence, but each carries a distinct routing decision, so little 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?

An output schema exists, so return values need no explanation, and the description still clarifies what the default response includes. Combined with the failure handling and sibling routing, an agent has everything needed to call this 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 description coverage is 100%, so the schema already documents id, private, and whole_note. The description restates the whole_note contrast (whole note vs matching section) but adds no format or syntax detail beyond the schema. Baseline 3 is correct when the schema carries the parameter 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?

States a specific verb and resource — 'Read one search_notes result by its id' — and immediately scopes it as read-only and item-level. An agent can distinguish it from search_notes (which produces these ids) and from read_note 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?

Explicit sequencing ('Use it right after search_notes') plus named alternatives with the exact condition that selects each: around_result for neighbouring sections, read_note before editing, read_file_text for known paths. It also covers the failure path — search again if the id is unknown or the folder was locked.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark it read-only and closed-world, and the description adds real behavioral detail beyond them: the 60,000-character truncation with self-disclosure, and concrete failure modes (unsupported file types, scanned or password-locked PDFs, missing paths) reported as plain messages.

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, front-loaded with the core action and formats, then usage routing, then limits and failure behavior. No sentence is 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?

An output schema exists so return values need no explanation, and the description covers format support, size limits, error conditions and sibling routing. Nothing an agent needs 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 coverage is 100%, so path, folder and private are already documented in the schema, including the example path format and the folder/private semantics. The description adds little parameter-level meaning 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 and resource ('Read the text inside a note or file by its path') and enumerates the supported formats (Markdown, txt, CSV, JSON, YAML, .docx, PDF). It clearly separates itself from siblings by naming open_result, read_note, list_notes and recent_changes in the relevant roles.

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 explicit routing: use it for attachments and exact paths from list_notes or recent_changes, use open_result for search results, and read_note before an edit. Both when-to-use and when-to-use-something-else are spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations by clarifying that it returns exact saved text with the info block and that it is intended for copying old_text exactly before a replacement. The read-only behavior is also stated, though that overlaps with readOnlyHint=true. It does not contradict the 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?

The description is front-loaded with the core action and then immediately routes the agent to alternatives. It is appropriately sized with no filler; every sentence contributes to selection or correct invocation.

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?

This is a simple read tool with full schema coverage, an output schema, and annotations covering safety. The description supplies id provenance, exact-read behavior, and sibling alternatives, so an agent has everything needed to call 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 description coverage is 100%, so the schema already documents both id and private. The description reinforces the id source with search_notes or handed note ids, but does not add meaning beyond the schema and does not mention the private parameter's semantics.

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: read the exact text of a note as saved, including its info block, by a search_notes or handed note id. It explicitly distinguishes this tool from siblings open_result and read_file_text, so an agent can identify its role without opening 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?

It gives explicit usage guidance: use before replace_in_note so old_text can be copied exactly, use open_result for shorter question-answering reads, and use read_file_text for path-known notes or files. These alternatives and conditions are stated directly.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and openWorldHint=false, and the description adds real context beyond them: private-folder files are excluded, results are newest-first, and the cap is 50. 'Read only' merely restates the annotation and the return shape is covered by the output schema, so it stops short of 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?

Front-loaded with the core behavior, then exclusions, then alternatives and next step — a sensible order. A few clauses restate structured data ('Read only', 'at most 50'), which keeps it from a perfect score.

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 single optional-parameter read tool with an output schema and annotations, the description covers scope, exclusions, ordering, alternatives, and the natural follow-up call. Nothing an agent needs to invoke 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 coverage is 100% and the limit parameter is fully documented in the schema (default 15, max 50). The description only echoes 'up to limit, at most 50', adding no new semantics such as what ordering or counting rules apply to the limit. Baseline 3 applies when the schema does the work.

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 ('List the notes and files changed most recently') plus ordering ('newest first') and scope ('in every unlocked folder'). It explicitly distinguishes itself from search_notes (topic lookup) and list_notes (folder browsing), so an agent can route without opening 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?

Gives concrete when-to-use triggers ('what did I work on lately', 'pick up where the person left off') and names the two alternatives with the conditions that select them. It also gives the follow-up action (read_file_text by path), leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations: discloses the exact-match/unique occurrence precondition and the failure mode ('nothing is saved and the error says how many times it was found'), the Allow edits permission requirement, that each save creates a version the person can undo, and what is returned. The annotations only say non-destructive and closed-world, so this context is genuinely additive.

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 core constraint, then the addressing options, then the alternatives, then side effects. Dense but every clause carries information an agent needs before calling.

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 mutating tool with an output schema present, the description covers the prerequisite read, the failure condition, permissions, reversibility, and returns the saved path. Nothing material to a correct invocation 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 coverage is 100% and the parameters already document id vs path, folder, and private in detail. The description's path-vs-id advice largely restates the schema's own 'stays valid after edits, unlike a search id' note and says nothing about folder or private, so it adds little beyond the structured fields.

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 ('Change part of an existing note: replaces old_text with new_text') and immediately distinguishes itself from append_to_note and create_note by naming both siblings. An agent can pick this over the alternatives 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?

Explicit routing: use append_to_note to add at the end, create_note for a new note, and read_note first to copy old_text exactly. It also gives a selection rule between the two addressing modes (path is best for several edits in a row because it stays valid; otherwise a search or handed id).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description is consistent ('Read only'). Beyond that it discloses non-obvious behavior: searches every unlocked folder simultaneously, results are ranked best-first, private notes appear only as a locked placeholder, and it reports explicitly when nothing matches — details no annotation or schema conveys.

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?

Core information is front-loaded and every sentence carries content. It is somewhat long with several clauses packed into one sentence about results and private notes, but no filler warrants a deduction beyond that.

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?

An output schema exists, so the description need not detail return values, yet it briefly does anyway ('ranked results, best first'). Combined with the usage routing, private-note caveat, and empty-result behavior, an agent has everything needed to invoke and interpret 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 description coverage is 100%, so all three parameters are already documented in the schema, and the description largely restates those semantics (private gating, plain-words query). It adds context about searching all unlocked folders but no new syntax or format guidance. 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?

The description opens with a specific verb and resource ('Search the person's notes by meaning and words') and specifies the scope ('in every unlocked folder at once'). It is immediately distinguishable from sibling tools like list_notes and read_note, which operate on paths rather than semantic queries.

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 an explicit selection rule ('use it when you know what a note is about but not where it is'), names two alternatives with their own roles (list_notes for browsing by path, recent_changes for the latest work), and provides the follow-up step ('call open_result with an id'). The private-note condition is also spelled out as a when-to-use constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already confirms this is a safe read, so the description's 'Read only' line is redundant. However, it adds useful behavioral context beyond annotations: it discloses the returned permission level (read vs. edit), folder lock status, private subfolder visibility, and a re-invocation trigger when a folder is locked or unknown.

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 well-structured and front-loaded with 'Start here.' Each sentence contributes: the resource listing, the permission note, the no-input cue, the invocation triggers, and the sibling routing. There is 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?

Given the simple zero-parameter status check, the presence of annotations (readOnlyHint, openWorldHint) and an output schema, the description covers everything an agent needs: what is listed, when to call it, how to use the results, and where to go for folder contents. No gaps remain.

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?

The tool takes zero parameters, so the baseline is 4. The description simply says 'no inputs', which aligns with the empty schema and clarifies there is nothing to supply.

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 (lists) and resource (memories/folders), and adds what each entry contains: name, unlocked status, note count, private subfolders, and app permission level. It also distinguishes itself from the sibling list_notes by directing that sibling for viewing folder contents.

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 explicit when-to-use instructions: 'Start here', 'Call it first in a chat', and 'again when another tool says a folder is locked or unknown'. It also names the alternative list_notes for inspecting folder contents and explains how to use the returned names as folder= in other tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond annotations: deletion is delayed, the user can restore for 7 days, permanent deletion follows, the agent cannot restore it, and the operation requires edit permission. These are exactly the behavioral details an agent needs before mutating user data.

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 action and retention behavior in the first two sentences, then adds the safety warning, alternative tool, permission requirement, and failure mode. Every sentence earns its place with 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?

Given the available annotations and output schema, the description fills in the important operational gaps: recoverability window, eventual permanence, restoration limits, permission requirement, alternative tool, and failure behavior. Nothing material is missing for correct invocation.

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 path, folder, and private are already documented in the input schema. The description adds only a note that missing paths fail with a plain message, but does not add extra semantics for folder or private beyond the schema. 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: putting a note, file, or subfolder and its contents into the app's trash. It names move_note as a different action, making it distinguishable from siblings without opening 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?

Explicitly says to trash only what the person asked to remove and to use move_note for archiving or renaming instead. It also gives prerequisites (Allow edits) and failure behavior, so the when/when-not guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.