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

With no annotations, the description carries the full burden. It correctly signals that this is a write operation and gives a useful behavioral warning that add_note may create duplicates if a similar note already exists. However, it does not disclose what happens on duplicate titles, whether tags are optional defaults, or the shape of the created-note response (though an output schema exists).

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 short sentences, each with a distinct job: state the action, give usage triggers, and instruct pre-call search. No filler or redundant restatement of 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 straightforward create operation with a complete schema and an output schema, this is nearly complete. The main gap is not explicitly naming the sibling search tool in the 'search first' instruction, but the existing sibling list makes the intended workflow recoverable.

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 input schema already documents title, body, and tags. The description adds no parameter-level detail, so it stays at the baseline for fully documented schemas.

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 the precise verb-object pair 'Save a new note', identifying both the action and resource. It also marks the operation as creating rather than searching, deleting, or retagging, so it is clearly distinguishable from sibling 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?

It gives concrete triggers ('when the user wants something written down, remembered, or captured for later') and instructs the agent to search first if a similar note may exist. It doesn't name the search tool explicitly or state a hard when-not-to-call condition, but the intended routing is clear.

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 annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is known. The description adds useful context beyond that: the deletion is permanent, and the agent must obtain user confirmation before invoking. This goes beyond simply restating the annotation information.

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 two short sentences with no fluff. The core action is front-loaded, and the critical user-confirmation requirement is stated immediately after. Every sentence 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 simple single-parameter deletion tool with a destructiveHint annotation and an output schema, the description covers the essential operational requirements: what is deleted, how it is identified, and the prerequisite confirmation step. Nothing necessary for 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?

The schema already provides 100% coverage for the single parameter note_id, including a description 'ID of the note.' The description's phrase 'by ID' reinforces this but does not add new semantic detail beyond what the schema already gives. With full schema coverage, 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 action ('Permanently delete') on a specific resource ('a note') with a clear access method ('by ID'). This clearly distinguishes it from the sibling tools add_note, search_notes, and retag_notes, all of which perform different operations.

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 instruction to 'Confirm with the user first' provides a clear, explicit context for when this tool should be invoked: only after user confirmation. It does not explicitly list alternative tools or exclusion criteria, but the operation is distinct enough from the siblings that the primary usage context is clear.

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?

With no annotations, the description carries full behavioral disclosure. It states the bulk/global nature of the operation, which is the key behavioral trait. However, it does not mention what happens if new_tag already exists (e.g., merging), whether the operation is reversible, or that it mutates notes across the entire workspace. The schema labels parameters but not side effects.

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 sentence that front-loads the action and scope with no filler words. Every word earns its place: 'rename', 'tag', 'across every note', and 'carries it' all contribute to the tool's purpose and behavioral scope.

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 two-parameter tool with full schema coverage and an output schema, the description is largely complete for correct selection and invocation. It could clarify behavior when new_tag already exists, but this is a minor edge case. The core usage context and parameter semantics are both adequately covered.

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%, with both old_tag and new_tag described in the input schema. The description adds no parameter-level details beyond the schema. It does add useful context about global scope, but this is unnecessary for parameter interpretation. A baseline 3 is appropriate since the schema already documents the parameters.

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 action ('rename') applied to a specific resource (a tag) with clear global scope ('across every note that carries it'). This cleanly distinguishes the tool from siblings like add_note, search_notes, and delete_note, which operate on notes rather than tags.

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 global scope makes it clear this is the tool for renaming a tag across all notes rather than within a single note. There are no explicit when-not-to-use statements or alternatives, but the sibling set contains no competing tag-rename tool, so the invocation context is unambiguous. The description could have been more explicit about per-note tag edits being out of scope, but it is clear enough.

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 readOnlyHint=true. The description adds the important boundary behavior that an empty query with no tag returns every note, which an agent might otherwise treat as an invalid or no-op call. It does not conflict 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 compact sentences: the first states the function, the second states the boundary condition and gives a concrete use case. No filler or repetition of 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 read-only 2-optional-param search tool with an output schema, the description covers what it searches, the empty-result boundary, and the main workflow context. Nothing essential is missing for an agent to select and 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 100%, so baseline is 3. The description adds the interaction rule for query and tag ('and/or') and specifies the empty-query-with-no-tag behavior, which the schema does not. It could be more precise about how the two filters combine, but it adds genuine value beyond the schema 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?

The description opens with a specific action ('Find notes') and the matching criteria (text query and/or tag), making the tool's purpose unambiguous. It also distinguishes itself from the mutation siblings by its read-only search nature and the explicit duplicate-avoidance use case.

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 explicitly tells the agent to use this tool before adding a note to avoid near-duplicates, which is concrete usage guidance. It doesn't list exclusion cases or alternative search tools, but there are no other search siblings, so the context is sufficient.

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