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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the bar is lower, but the description adds little: it doesn't say whether the created note is returned, whether duplicate titles are allowed, whether tags must already exist, or what tags do at write time. Only the tag-format rule (lowercase, optional) adds behavioral value.

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 short sentences with the core action front-loaded and no filler. The second sentence is doing real work on the only non-obvious parameter.

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 needn't be described, and annotations cover the safety profile. Still, for a 3-parameter creation tool with 0% schema description coverage, the definition leaves required-ness, duplicate handling, and tag prerequisites unaddressed.

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 0%, so the description must carry the load. It does explain the 'tags' parameter (optional, lowercase, filtering semantics), but says nothing about 'title' or 'body' beyond the names, and doesn't state that both are required.

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 ("Create a note") that maps cleanly onto the CRUD sibling set (get_note, update_note, delete_note). It doesn't explicitly contrast itself with update_note or explain whether the note is created in a shared store, so it stops short of full sibling differentiation.

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?

No statement of when to use this versus update_note or how it relates to search_notes/list_tags. The only usage-adjacent hint is that tags are 'used for filtering', which implicitly points at search_notes but never says so.

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 destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds value beyond them by stating the deletion is permanent and that user confirmation is required, which is exactly the behavioral context an agent needs before invoking a destructive 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?

Two short sentences with zero waste: the operation is front-loaded and the confirmation requirement follows immediately. Nothing could be removed 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?

An output schema exists, so return values need not be explained, and annotations cover the destructive/idempotent profile. What is slightly missing is behavior on a nonexistent or already-deleted note_id, though idempotency is declared so the agent can infer safe retry semantics.

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 0%, so the single required parameter note_id is undocumented in both schema and description. However, the parameter is self-evident (an integer note identifier) and the description's scope word "note" aligns with it, so the gap is minor rather than harmful.

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 (delete), resource (note), and effect (permanently), so the agent knows exactly what the tool does and that it is irreversible. It does not explicitly name a sibling such as update_note to contrast with, but the destructive framing makes it distinguishable from the other note tools.

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?

"Confirm with the user first" is a procedural constraint rather than a when-to-use rule, and there is no explicit guidance on when to choose delete_note over e.g. update_note. Usage is implied by the destructive nature of the operation rather than stated.

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, so the safety profile is covered. The description adds only that the full text (not a summary) is returned, which is modest added value; it says nothing about what happens for a missing or unauthorized note_id.

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?

A single front-loaded sentence with zero padding; appropriately sized, though its terseness is achieved partly by omitting necessary detail.

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 needn't be explained. However, for a tool whose only parameter is undocumented in the schema, the description should at minimum explain how to source the note_id; that gap leaves it only minimally complete.

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 0% — note_id has no description in the schema — so the description must compensate and does not. It never clarifies that note_id is a required integer identifier or how an agent should obtain one (e.g., via search_notes).

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: 'Return the full text of one note.' The singular 'one note' implicitly contrasts with the sibling search_notes, but no sibling is named, so an agent must infer the boundary itself.

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?

No when-to-use or when-not-to-use guidance, no mention of alternatives like search_notes for finding notes or list_tags. The agent gets no routing signal beyond the bare purpose.

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, so the safety profile is covered. The description adds one piece of real value beyond that — each tag comes with a note count — but says nothing about whether deleted/archived notes are counted, whether the list is sorted, or whether it's paginated.

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?

A single short sentence with no wasted words; the key information (tag list plus per-tag counts) is front-loaded. Nothing is padded or repeated from structured fields.

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 a read-only annotation, an output schema to explain the return shape, and no parameters, this is nearly complete. The only remaining gap is scoping detail — which notes the counts include and whether results are ordered — which the output schema may or may not cover.

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 per the baseline a 4 applies. The description correctly implies there is nothing to filter or scope, which matches the empty 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?

The description clearly states the resource (tags) and the payload (count of notes per tag), so an agent knows it's an enumeration of tags with usage counts. It doesn't explicitly differentiate from siblings, but the sibling list is all note CRUD, so the distinction is implicit rather than stated.

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?

There is no when-to-use guidance, no mention of alternatives (e.g., search_notes for filtering by tag), and no statement of prerequisites or context. The agent must infer that this is a discovery/lookup helper for finding tag names before another call.

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, so safety is covered; the description adds genuinely new behavioral detail in the ranked ordering and the [brackets] highlighting convention in snippets. It stops short of covering pagination/limit behavior or what happens with zero matches. No contradiction with 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?

Two short sentences, no filler; the core purpose and result ordering come first and the snippet-format detail follows. Every clause carries information an 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?

Output schema exists, so return values need not be described, and the ranking plus bracket highlighting fill the main behavioral gap. The omission of limit semantics and any routing guidance versus siblings are the only remaining holes for a read-only three-parameter search 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 0%, so the description must compensate: it usefully clarifies that 'query' spans titles, bodies and tags, and that 'tag' accepts only one value (not a list). It says nothing about 'limit', leaving one of three parameters unexplained in both schema and description.

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 (full-text search) plus the fields searched (titles, bodies, tags) and the result ordering (best match first), which clearly separates it from get_note. It never names a sibling or states that it takes a free-text query rather than an identifier, so differentiation is implied 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?

The closing line 'Optionally filter by one tag' gives a usage hint for one parameter, but there is no guidance on when to search versus fetching a known note by ID or listing tags, and no exclusions. Usage is inferable from the name and purpose statement only.

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 only say readOnlyHint=false and destructiveHint=false; the description adds the crucial nuance that tags are wholesale replaced rather than merged, which is effectively a data-loss behavior the annotations do not convey. It stops short of stating failure behavior for a bad note_id or whether fields can be cleared.

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 tight sentences, no filler, and the most surprising constraint (tag replacement) is placed where it will be read before 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?

An output schema exists so return values need no explanation, and the mutation model is covered. Missing is what happens when note_id doesn't resolve, and how the anyOf-null defaults interact with intent to clear a field — an agent could easily mis-call this.

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 0%, so the description carries the burden. It does explain the omit-means-unchanged rule and the tags replacement rule, but says nothing about title vs body, the required note_id, or whether passing null clears a field versus skipping it — a real ambiguity given every optional param defaults to null.

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?

"Change a note" gives a clear verb+resource and the object is unambiguous given siblings add_note/get_note/delete_note. It doesn't explicitly differentiate itself from the other note tools, but the mutation semantics set it apart well enough.

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 establishes partial-update semantics ("Only the fields you pass are updated"), which tells the agent how to invoke it, but never says when to prefer it over siblings or what prerequisites exist (e.g. note must already exist). Usage is implied rather than guided.

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