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

Annotations already declare destructive, non-readOnly, idempotent behavior, so the bar is lower. The description adds genuinely useful context the annotations cannot: the server will prompt the user for approval when the plan is pending, the model cannot self-approve, and a read-back confirmation occurs after the write.

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, no filler, with the core action front-loaded and the approval caveat immediately after. 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?

No output schema exists, but the description covers the read-back confirmation and the pending-approval branch, which is the main failure mode. It omits error cases for an unknown or already-applied plan_id, a minor gap for a single-parameter 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 0%, so the schema contributes no meaning for plan_id; the description implies it identifies a previously proposed plan but adds no format, source, or valid-value detail (e.g., where to obtain a plan_id). Baseline 3 given one undocumented parameter the description only partially compensates for.

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 (write) and resource (an approved plan to Anki) plus a follow-up verification step, which clearly separates it from the propose_* siblings that create plans. It stops short of naming the sibling tools explicitly, so differentiation relies on the word 'approved'.

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 condition under which it applies (an already-approved plan) and explains what happens if the plan is still pending, which tells the agent not to expect a silent success. It never explicitly points to list_plans or reject_plan as alternatives, so the routing guidance is contextual 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 establish the safe read-only, closed-world profile, and the description adds the return shape (note ids, model, decks, tags, field excerpts), which matters since there is no output schema. It does not disclose pagination or the default result cap, so it stops short of full transparency.

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, no filler: the core mechanism (syntax search) is front-loaded with an example, followed by the return contents. 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 read-only search tool with no output schema, the description covers both the query language and the returned fields, which is most of what an agent needs. The missing piece is result-limiting behavior (limit/default 20), which an agent calling it repeatedly would want to know.

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 does well for 'query' by specifying the Anki search syntax with a worked example, but says nothing about 'limit' or the default of 20, leaving one of two parameters undocumented in both schema and prose.

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 (search) and resource (notes) and backs it with a concrete Anki-syntax example, so an agent immediately understands this is a syntax-driven note query. It does not explicitly distinguish itself from the sibling get_notes, but the example query format makes the distinction inferable.

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 example query implies usage context, but there is no explicit 'use this when…' guidance and no mention of the sibling get_notes as the alternative for id-based retrieval. The agent must infer the search-vs-fetch split on its own.

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 and scope are covered. The description adds one genuinely useful behavioral detail beyond that: the 100-note cap, which tells the agent output may be truncated. It does not cover behavior for invalid/unknown IDs or what happens when more than 100 IDs are supplied.

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 terse sentence with zero padding and the key content (full fields, tags, 100-item limit) up front. The brevity is a virtue structurally, though it borders on under-specification for a tool with no other documentation.

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 annotations cover the read-only profile. Still missing for the agent: how notes are identified, ordering, and behavior at the 100-note boundary or with invalid IDs, which matters given 0% parameter 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 description coverage is 0% for the single note_ids parameter, so the description must carry the load and it barely does. 'up to 100 notes' hints at a size bound on the input, but nothing explains that the array holds note identifiers, their integer format, or how missing IDs are handled.

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 fragment 'Full fields and tags of up to 100 notes' conveys the resource and what is returned (full fields plus tags), but omits the verb entirely and never states that notes are selected by their IDs. It draws no line against the sibling find_notes, so an agent cannot tell which retrieval tool fits 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?

There is no when-to-use guidance: nothing says whether this is the right choice for fetching notes by ID versus find_notes for querying, and no prerequisites or exclusions are given. Usage must be inferred entirely from the name and sibling list.

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 a genuinely non-obvious behavioral fact: the response exposes per-deck write permission for this server, not just deck names. It stops short of describing ordering, pagination, or the exact return shape.

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 with zero waste, front-loaded on the primary action (list decks) with the secondary detail (write permission) trailing. Nothing redundant with the 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?

For a zero-parameter read-only list tool, the description effectively doubles as a return-value summary (deck identifiers plus write-access flags), which compensates for the absent output schema. Minor gap: no mention of ordering or result size limits.

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 there is nothing for the description to disambiguate. Schema coverage is 100% and the empty argument object matches the description's no-filter behavior.

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 all decks") plus a scope qualifier — which decks the server may write to — that no sibling exposes. An agent can distinguish it immediately from propose_create_deck or the notes tools 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?

Usage is implied: call it to enumerate decks, presumably before proposing note or deck operations. However, it names no alternative and states no explicit condition for when this tool is the right choice versus, say, listing plans. Adequate but leaves routing 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered structurally. Beyond that, the description discloses nothing about return behavior, ordering, or pagination, so it adds little behavioral context.

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 compact sentence-fragment with no waste. It is front-loaded, though being a fragment it lacks an explicit action verb.

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 read-only nature. However, for a filterable list tool the description never states that status acts as a filter or how results are bounded, leaving a modest gap.

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% and the single 'status' param has no description or enum in the schema. The description compensates by enumerating the valid values (pending, approved, applied, rejected, expired, invalid, failed), which is exactly the information the schema lacks.

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 the resource ('Plans') and enumerates their possible states, but omits an explicit verb – it relies on the tool name 'list_plans' to convey the listing action. It gives no differentiation from siblings like list_decks or apply_plan.

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 guidance on when to call this versus alternatives such as list_decks, apply_plan, or reject_plan, nor any prerequisites or exclusions. Usage must be entirely inferred from the name.

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?

readOnlyHint=true is consistent with the 'dry run' framing, so no contradiction. The description adds real behavior beyond annotations: cloze syntax is validated for the entire batch, implying all-or-nothing failure semantics, though it doesn't say what the caller receives on success or failure or that a plan must be applied.

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 tight sentence with no filler, and the dry-run constraint is front-loaded. It is arguably too terse for the workflow it represents, but every word 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 two-parameter batch tool with no output schema and no annotation coverage of the propose/apply workflow, the description leaves the return value (a plan handle?) and the 'deck' argument unaddressed. The batch-validation note is the main gap-filler, but the plan lifecycle the name implies is not explained.

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% at the top level and the description names neither required parameter. The 'deck' parameter's format (name vs ID) is undocumented anywhere, and 'notes' is only described obliquely via 'one or many' and batch validation.

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 (adding cloze notes) and adds scope detail ('one or many') plus a dry-run qualifier. It is distinguishable from sibling propose_add_notes only by the word 'cloze', with no explicit statement of how the two differ.

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?

'Dry run' implies the caller must later apply the result, but the description never mentions apply_plan/reject_plan or when to choose this over propose_add_notes. Usage must be inferred from the naming convention and sibling list.

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 safety (readOnlyHint=true), but the description goes well beyond them: it enumerates the exact checks the dry run performs (exact duplicates skipped, same-front-different-back left to the user, similar fronts flagged, tags checked against taxonomy) and reinforces that nothing is written. That is precisely the behavioral context an agent needs to interpret the result.

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 dry-run nature, then the check list, then the next-step instruction. No filler and nothing 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?

For a two-parameter read-only preview with no output schema, the description covers purpose, validation behavior, and the follow-up workflow. The only gap is that the returned plan/scan results and the deck argument's semantics are not described, but annotations and the small schema keep that minor.

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 meaning of deck and notes. It explains the front/back structure and that tags are validated against a taxonomy, which adds real semantic value, but the deck parameter is never mentioned and the notes array shape is only partially implied. Partial compensation for the coverage gap.

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 opening clause states a specific verb and resource ('Dry run for adding basic (front/back) notes, one or many'), and 'basic (front/back)' implicitly separates this from the cloze-note sibling. An agent can tell the operation apart from propose_add_cloze_notes or propose_update_note without reading 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?

It gives clear context — this is the preview step, and 'call apply_plan after the user sees it' names the required follow-up explicitly. It does not call out alternatives by name (e.g. cloze notes or update), so the selection guidance is clear but not fully exclusive.

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, so the agent knows this makes no changes, and the 'dry run' wording is consistent with that. The description adds a real constraint beyond annotations — scope 'only inside the writable decks' — which is genuinely useful context, but it omits what the dry run produces (a plan) and how it feeds the apply/reject flow.

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 no filler. It is efficiently structured, though the brevity edges toward under-specification rather than tightness.

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 propose/dry-run tool embedded in a plan-apply workflow, the description omits the most important context: that it yields a plan consumed by apply_plan/reject_plan, and any constraints on the name. With a 1-param schema at 0% coverage and no output schema, the description should carry more of this burden.

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% and the description does not mention the single 'name' parameter at all, so it adds nothing beyond identifying the action. Even though 'name' is fairly self-evident for deck creation, the description makes no attempt to clarify 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 action (dry run for creating a deck) with a clear verb+resource, and the 'propose_' naming plus the parenthetical scope make it distinguishable from write siblings like apply_plan. It does not, however, explicitly name the alternative it pairs with, 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?

The phrase 'dry run' implies a non-committing preview, but the description never states when to use this versus apply_plan, nor that a resulting plan must be applied or rejected afterward. No exclusions or prerequisites are given.

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: 'dry run' makes clear no deletion occurs. Beyond annotations it discloses the affected scope (notes and their review history), a config gate, and a 50-id cap, which are useful behavioral details. It doesn't address the proposal lifecycle or whether the request is reversible.

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 with the key qualifier ('dry run') front-loaded, followed by the constraints. No filler or 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?

For a one-parameter dry-run tool with no output schema and annotations covering its safety profile, the description supplies the essential prerequisites and limits. The main omission is how the resulting proposal is acted on by sibling tools like apply_plan/reject_plan.

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% for the single parameter, so the description must compensate. 'At most 50 ids' merely restates the schema's maxItems=50, and 'no delete-by-query' only implicitly clarifies that explicit integer ids are required. It adds marginal meaning over 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: a dry run for deleting notes plus their review history. It clearly distinguishes itself from destructive siblings by being a non-mutating dry run. It does not explicitly name how it relates to apply_plan/reject_plan, but the 'propose_' naming and 'dry run' wording make the role inferable.

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 a real precondition ('off unless the user enabled it in the config') and hard constraints ('at most 50 ids, no delete-by-query'). This tells an agent when the call is valid and its limits. It stops short of naming alternatives (e.g., how to obtain ids or how the proposal is consumed).

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 genuinely useful behavior beyond that: user-set flags are skipped and never overwritten, and 0 clears an agent-set flag. This is real context an agent couldn't derive from 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?

Two tight sentences, zero filler, with the dry-run framing and the color semantics front-loaded. 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 proposal tool with no output schema and no annotations covering results, the description should say what the dry run produces and how to commit it (e.g. via apply_plan). It covers flag-overwrite behavior well but leaves the workflow outcome unexplained.

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 explains color semantics well (default 4 = blue, 0 = clear an agent-set flag), but card_ids is left entirely undefined beyond its obvious meaning, so the compensation is partial.

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 ('flagging cards') and clarifies the mode ('Dry run'), so the agent knows this proposes rather than applies a change. It does not explicitly contrast itself with the other propose_*/plan siblings, but the name and verb make the intent unambiguous.

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?

'Dry run' implies this must be followed by a commit step, and the sibling set (apply_plan, reject_plan) supports that workflow, but the description never names apply_plan or states when to prefer this over alternatives. Usage is only implied, not 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 readOnlyHint=true annotation already covers safety, and the description is consistent with it ("dry run"). It adds non-schema context: the operation mirrors Anki's set due date and the tool is disabled unless enabled, which the agent cannot learn from annotations alone. It stops short of explaining the resulting plan or how it feeds into apply_plan.

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?

Very tight: one sentence plus a trailing clause, with the operation front-loaded before the format example and the enablement caveat. No wasted words, though the terseness borders on under-specification.

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-param dry-run tool with no output schema it covers purpose, format, and the enabled/disabled caveat. It omits what a successful proposal produces and how it relates to apply_plan/reject_plan, the closest siblings, leaving the workflow relationship implicit.

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%, so the description carries the burden. It usefully documents the days format ("days='0' or '1-3'"), but card_ids is unexplained and no detail is given on accepted ranges, indexing, or constraints — partial compensation for a two-parameter tool.

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 (propose/dry run) and resource (rescheduling cards / Anki set due date), and the parenthetical makes the operation concrete. It does not explicitly name a sibling or how it differs from other propose_* tools beyond the shared prefix, so sibling differentiation is only implied.

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?

"Dry run for rescheduling cards" implies this is a staging/no-op operation, and "Off unless enabled" hints the tool may be gated. There is no explicit when-to-use, when-not-to-use, or named alternative, so usage is left to inference from the propose_* naming convention.

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, so the safety profile is covered; the description adds real behavior beyond that: a before/after diff is produced, and the plan is refused if the note changed before apply_plan (stale-write protection). It does not say what the plan returns (e.g. a plan id) or how the refusal surfaces.

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 plus one conditional clause, all front-loaded: what it is, what it produces, and the concurrency guard. 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 read-only staging tool with no output schema, the description covers purpose, effect (diff), and failure mode (stale-write refusal) and routes to apply_plan. The remaining gap is the shape of the returned plan and the accepted value format for fields/tags.

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 names the two optional concepts ('fields' and 'tags') and the single-note scope, but gives no format guidance — notably that fields is a name→value map — and never addresses note_id. Partial compensation only.

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 ('Dry run for editing one note's fields and/or replacing its tags') plus the scope ('one note'). An agent can distinguish this from propose_add_notes, propose_delete_notes, and apply_plan 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?

Explicitly frames this as a dry run and names apply_plan as the follow-on step, which tells the agent where this fits in the propose/apply workflow. It stops short of stating when NOT to use it or what alternative stages other mutations, but the 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?

Annotations declare this is a non-read-only, non-destructive, non-open-world write, which tells the agent the plan is not truly deleted. The description's word 'discard' leaves that ambiguity unresolved and says nothing about reversibility, permissions, or what happens to the plan afterward. With no annotation contradiction, but little added context, 2 is appropriate.

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, front-loaded sentence with no filler. It is efficient, though its brevity edges into under-specification rather than disciplined conciseness.

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 tool with no output schema and only sparse annotations, the description should explain consequences (plan discarded/rejected, effect on related plans, reversibility). It omits all of this, leaving the agent to infer behavior from the name alone.

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% and the description adds no meaning for either parameter. It never explains that plan_id identifies the plan to reject (it is required) or what the optional 'reason' field is for. Only the self-evident parameter names keep this above 1.

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 (discard) and resource (a plan), and adds the condition 'the user does not want', so an agent knows this is a rejection action. It does not, however, differentiate itself from siblings apply_plan/list_plans or explain how 'discard' differs from the propose_* proposal flow.

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 phrase 'the user does not want' essentially restates the tool name rather than providing actionable guidance. There is no mention of when to prefer reject_plan over apply_plan, no prerequisites (e.g., must a plan exist first), and no note that plan_id is required.

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