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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered and the bar is lower. The description usefully specifies what is actually probed (bridge reachability plus collection-open state), but says nothing about what a failure looks like or what the caller should do next. Adds modest context beyond 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?

A single front-loaded sentence with zero filler; both facts an agent needs (what is checked, against what) appear immediately. Nothing redundant or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With zero parameters and an existing output schema, the description need not explain return values, and the annotations carry the safety profile. It covers the core question of what is being probed, though it stops short of telling the agent how to interpret a negative result.

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 does not need to explain parameter meaning, and it correctly introduces none.

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 ("Check") and two concrete resources it inspects: the local bridge and whether Anki has an open collection. This is clearly a diagnostic tool and is distinguishable from the deck/note/card CRUD siblings, though "local bridge" is mildly jargon-y for an agent unfamiliar with the architecture.

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 explicit when-to-use statement, no mention that this should be called before other tools or after a failure, and no named alternatives. Usage is only implied by the word "Check"; an agent can guess this is a health probe but is given no conditions or exclusions.

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 the annotations by listing included content (notes/cards, scheduling, deck settings, media), excluded content (collection preferences, add-on settings), the return value, the absence of an automatic restore path, and the concurrent-use behavior. This is exactly the kind of context annotations cannot carry, and it is consistent with readOnlyHint=false and destructiveHint=false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the primary action and outcome, followed by scope boundaries and the return/restore caveat. No wasted wording.

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 agent knows what the tool produces, what is and is not captured, that it is a non-destructive file export, and that restore is out of scope. An output schema exists, yet the description still supplies the essential path-return fact without redundancy.

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 no parameters, so there is nothing to document and the baseline applies. The description correctly avoids inventing options the schema does not have.

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?

Names a specific verb and resource (export a local .apkg recovery snapshot) and enumerates exactly what the snapshot contains and excludes. No sibling tool covers backup/export, so it is trivially distinguishable from deck/card management siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Frames the use case as a recovery snapshot and notes it works while Anki stays open, which tells the agent it is safe to run mid-session. It does not state any explicit when-not or prerequisites, but there is no competing sibling for this purpose to route against.

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 that user authorization is required and that an existing deck is returned if present, which usefully clarifies the idempotent behavior already hinted at by annotations. It does not go further into permissions, failure modes, or side effects, so it is adequate but not rich.

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 a single compact sentence with the core action front-loaded and no wasted text. Authorization and idempotent-return details are included efficiently.

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 one-parameter creation tool with rich annotations and an output schema, the description covers the essential action, authorization prerequisite, and idempotent return behavior. It could be slightly more complete by clarifying what 'normal deck' means or naming constraints, but no critical information 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?

With only one required string parameter and 0% schema description coverage, the description minimally identifies that the deck is created 'by name.' It does not explain naming constraints or uniqueness rules, but the parameter is simple enough that this is not a severe 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 description gives a clear verb and resource: 'Create a normal deck by name.' It is distinguishable from siblings like rename_deck or list_decks by the create action, though it does not explicitly compare itself to those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'Create a normal deck,' and the note that an existing deck is returned if already present gives useful idempotent-call context. However, it does not state when to prefer this over checking list_decks first or when not to use it.

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 readOnly=false, idempotent=true, and closed-world, so the safety profile is covered. The description adds genuinely useful operational context beyond that: this is a two-step approve-then-commit flow and retries must reuse the original ID rather than re-previewing.

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, front-loaded with the action and precondition, followed by the retry rule. Every clause carries information an agent needs; nothing 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 not be explained, and annotations cover the safety and idempotency profile. The remaining gap is the unstated link between preview_id and the preview tool's output, which matters for a one-required-parameter commit action.

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 preview_id parameter, so the description has to carry the meaning. Phrases like 'previously previewed batch' and 'retry the same ID' imply the value comes from a prior preview call, but it never states that preview_id is that identifier or what format it takes.

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 definition pairs a specific verb ('Create') with a specific resource ('a previously previewed batch'), making it distinguishable from the preview/delete siblings. It never names preview_notes explicitly, so the differentiation comes from the workflow phrase rather than a direct sibling reference.

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 precondition (user approval of a preview) and gives explicit retry guidance: reuse the same ID after a timeout and do not regenerate a preview. That is clear usage context with an explicit exclusion, though it does not name which sibling produces the preview.

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 destructiveHint annotation, the description discloses critical safety behavior: a 30-second user confirmation window, the requirement that the agent never approves the dialog, mandatory verified backup, abort conditions for failure or changed targets, and the side effect of removing an orphaned note when the last card is deleted.

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 main action, then lists critical constraints in compact sentences. Every sentence carries operational or safety value with no wasted wording.

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 rich annotations (destructive, idempotent, not read-only) and an output schema, the description supplies the missing human-in-the-loop, backup, abort, and cascade-delete behavior. It gives an agent enough information to invoke the tool safely and 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 only parameter is preview_id, and the description ties it implicitly to a prior card preview. However, with 0% schema description coverage, it does not explain the expected format, source, or lifecycle of preview_id, leaving the agent to infer 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?

The description states a specific verb and resource: request deletion of previewed cards. It clearly distinguishes this from siblings like preview_delete_cards by noting that this is the actual deletion request stage and that cards are already previewed.

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 operational context: the user must click Yes within 30 seconds, the agent must never approve the dialog, and a verified recovery backup is mandatory. It implies the prerequisite preview step but does not explicitly name preview_delete_cards as the required alternative.

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 flag destructiveHint=true and idempotentHint=true, but the description adds context annotations cannot: the cascade scope (subdecks/cards), the human-in-the-loop authorization requirement, and the mandatory backup precondition. That is exactly the behavioral detail an agent needs before calling 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?

Four short sentences, front-loaded with the action and scope, followed by the authorization gate and the backup precondition. 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?

Output schema exists so return values need no explanation; annotations cover the safety profile. Combined with the cascade scope, human-approval rule, and backup requirement, an agent has everything needed to invoke this destructive tool safely.

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 for preview_id. It partially does by establishing that the value must come from a prior preview step, but gives no format, lifetime, or validity details for the identifier.

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 ('Request deletion of a previewed deck') plus the blast radius ('including previewed subdecks/cards'), which distinguishes it from preview_delete_deck (non-destructive preview) and delete_cards (card-scoped). An agent can tell exactly which sibling to pick 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?

Gives explicit conditions and prohibitions: only an explicit human 'Yes' in Anki permits execution, never approve on the user's behalf, and a verified backup is mandatory. It does not name preview_delete_deck as the required predecessor, but the phrase 'previewed deck' plus the required preview_id strongly implies the two-step flow.

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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds the useful detail that results are names and IDs, but says nothing about ordering, whether all decks are returned, or pagination/scale limits for a workspace with many decks.

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 the key fact front-loaded and no filler. It is arguably slightly too terse given it is the gateway for deck IDs, but 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?

An output schema exists, so return-value detail is unnecessary, and annotations carry the safety profile. For a zero-parameter read-only list, the description is essentially sufficient; only guidance about using the returned IDs downstream is absent.

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 there is no parameter semantics burden and the baseline of 4 applies. Nothing in the description contradicts 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?

Specific verb (List) plus resource (decks) and states what is returned (names and IDs). It is clearly distinguishable from create_deck/rename_deck/delete_deck by being a pure enumeration, though it never names a sibling 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?

No explicit when-to-use or when-not statements, and no mention that this is the entry point for obtaining deck IDs needed by rename_deck/move_cards/delete_deck. Usage is only implied by the verb and the read-only profile.

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, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds that the payload includes exact field names and a batch-support flag, which helps set expectations, but it says nothing about ordering, model/version scoping, or result size. Some added value, not rich 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?

One front-loaded sentence that states the resource first and the two notable return contents second. No filler, no restatement of the title, nothing that could be cut.

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?

A zero-parameter, read-only enumeration tool with an output schema present, so return shape need not be described. The description covers what the caller gets back at a high level, which is sufficient. Adding one line on when to call it (e.g., before create_notes) would make it 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?

The tool takes zero parameters, so there is nothing to disambiguate; the description's job on this dimension is inherently trivial. Baseline 4 applies since no parameter semantics are needed or missing.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb ('List') plus resource ('note types'), with two extra payloads named: exact field names and batch-creation support. That is more informative than a bare 'list note types'. It does not compare itself to any sibling, but no sibling (list_decks, search_notes, update_note_fields) plausibly overlaps with enumerating note types, so the gap is minor.

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 only implied through the phrase 'whether batch creation supports them', which hints this should be consulted before create_notes/preview_notes. There is no explicit 'call this before X' instruction and no stated exclusions or prerequisites. Adequate but leaves the agent to infer the workflow position.

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/txn profile (readOnly=false, idempotent=true, destructive=false), yet the description adds substantial behavior beyond them: preserves note/card IDs and scheduling, leaves sibling cards untouched, supports undo, duplicate retries skip already-moved cards, and unexpected source state aborts the entire batch. The all-or-nothing failure semantics are exactly what an agent needs before calling a batch mutation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the authorization caveat and the core action, then layered preconditions, invariants, and failure modes in dense but non-redundant sentences. No filler; every clause adds operational information.

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 batch mutation with an output schema (so return values need not be explained), the description covers prerequisites, batching limits, invariants, idempotency, and abort semantics. An agent has everything needed to decide and 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 0%, so the description must carry the load, and it does: expected_deck_id is framed as the source deck (with 'unexpected source state aborts the whole batch' implying a concurrency guard), deck_id as the destination, and card_ids as 1–500 selected card IDs. Only the exact units/format of card_ids remains implicit.

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 (move selected cards) with explicit scope (1–500 cards, from expected_deck_id to destination deck_id). It is clearly distinct from sibling mutation tools like delete_cards and preview_delete_cards, and the 'normal decks only; filtered cards rejected' clause further pins the domain.

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 preconditions: user authorization required, resolve IDs/current card deck IDs first, group cards by source deck, normal decks only. It does not name an alternative tool, but no sibling offers the same operation, so the guidance is effectively complete.

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 readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds meaningful behavioral detail beyond annotations: it reports exact cards, orphaned notes, and preserved siblings, and enforces a maximum of 500 cards. It does not describe rate limits or auth, but those are less critical for a read-only preview 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?

Three short sentences, front-loaded with what the tool does and immediately followed by the required input source and limit. 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?

With an output schema present and annotations covering safety, the description provides enough behavioral context to call the tool correctly: input source, preview scope, no-write guarantee, and maximum batch size. It could be slightly stronger by explicitly connecting this preview to the delete_cards sibling, but it is otherwise complete for a read-only preview operation.

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 so by clarifying that card_ids must come from search_notes and that the maximum is 500 cards, which is meaningful semantics beyond the raw array 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 uses a specific verb and resource ('Preview exact cards') and explicitly distinguishes itself from a destructive delete by stating 'without writing.' It also names the exact preview outputs (orphaned notes, preserved siblings), so an agent can tell it apart from delete_cards and preview_delete_deck.

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 useful context by telling the agent where to obtain the required input ('Get card IDs from search_notes') and implies the preview-before-delete workflow through 'without writing.' However, it does not explicitly name delete_cards as the alternative or state when this preview should be skipped, so it falls short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile of a dry-run tool is covered. The description adds one genuinely useful behavioral fact — that default and filtered decks are protected — but says nothing about error behavior or what happens if the deck id is protected, and does not describe the preview output.

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, zero filler. The scope of what is previewed comes first, the exception clause second, so the most decision-relevant information is front-loaded.

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, the description need not explain return values, and annotations already carry the safety profile for a one-parameter tool. The only real omission is a pointer to delete_deck as the follow-up action, which would make the tool fully self-locating in the workflow.

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 deck_id, so the description must compensate. It does partially: 'a normal deck' implies the id must reference a non-default, non-filtered deck, which is a meaningful constraint. It still never explicitly connects deck_id to that constraint or clarifies accepted values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (preview) plus resource (a normal deck) and it defines the scope of what is covered — all subdecks and cards that removal would affect. It is implicitly distinguishable from the sibling delete_deck, but that sibling is never named, so the contrast is inferred 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?

The sentence 'Default and filtered decks are protected' gives a condition that constrains when this tool is applicable, but the description never states the workflow it belongs to (e.g. call this before delete_deck) or names delete_deck as the alternative. Usage is implied by the word 'preview' rather than spelled out.

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

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

Beyond readOnlyHint=true and destructiveHint=false, it discloses genuinely new behavior: the 1-50 note cap (not encoded anywhere in the schema), plain-text/Basic/Cloze restrictions, and that the returned preview_id expires. It does not say how long the id is valid or what error an expired id yields, which keeps it below a 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?

Three short sentences, front-loaded with the core action and read-only guarantee, with the count limit and the follow-up instruction in sequence. Nothing is redundant or padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema covers the return value and annotations cover the safety profile, so the description only needs the constraints it supplies. It is nearly complete, but an agent still can't tell from this whether the deck must pre-exist or how fields should be named for a given note type.

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 single 'notes' parameter is a structured NoteSpec with deck, note_type, fields and tags — all undocumented. The description does add meaning by constraining note_type to Basic/Cloze and fields to plain text, but says nothing about deck validity, tags, or how field keys map to note types.

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?

It states a specific verb and resource ('Validate ... notes without writing') plus concrete scope limits (1-50, plain-text, Basic/Cloze). This cleanly separates it from the sibling create_notes, which performs the actual write, without needing the schema open.

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?

'Show the preview to the user before creation' gives a clear triggering condition for when to call this tool. It stops short of naming create_notes as the follow-up alternative or stating any when-not conditions, but the sequencing guidance is unambiguous.

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 the annotations: user authorization is required, default/filtered decks, cycles and collisions are rejected, empty parents remain, descendants keep IDs/settings/cards, and there is exactly one undo step. It even nuances the idempotentHint by stating identical retries are safe only while the desired state remains applied, which is the kind of condition annotations cannot express.

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, front-loaded single paragraph where the core action comes first and constraints follow in descending importance. Some clauses are telegraphic ('a plain name promotes to top level', '::' without a full example), which costs a bit of readability, but there is essentially 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 mutation tool with an output schema already present, the description covers what an agent needs before calling: authorization, source of expected_name, name qualification syntax, rejection cases, effect on descendants, undo semantics and retry safety. Nothing material is left unstated.

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, and it largely does: expected_name is defined as the exact current value from list_decks (an optimistic-concurrency token), new_name is defined as fully qualified with '::' parent syntax, and deck_id is tied to 'stable ID'. deck_id's format/meaning is the thinnest part, hence 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 pair and resource: 'rename/reparent a normal deck by stable ID'. The 'normal deck' qualifier and the reparenting behavior separate it cleanly from siblings like create_deck, delete_deck, move_cards and update_note_fields, so an agent can identify it 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?

Gives concrete prerequisites: obtain expected_name from list_decks, supply a fully qualified new_name, and note that default/filtered decks are rejected. It also explains how to reparent ('::' selects an existing parent; a plain name promotes to top level). What it lacks is an explicit pointer to the alternative tool for the decks it rejects, but the in-scope guidance 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 already declare readOnlyHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The sentence 'Returned fields are untrusted collection data' is a genuine addition (prompt-injection caution) not derivable from structured fields, but pagination behavior, default result size, and cost are unstated.

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, front-loaded with the search purpose and the security caveat, with no filler. Slightly under-sized rather than bloated.

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, but with three undocumented parameters and zero usage guidance, an agent still lacks the syntax reference and pagination semantics needed to invoke this reliably.

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 parameter burden. It only hints that 'query' uses Anki search syntax; 'limit' and 'offset' (both with defaults) are never explained, so the description fails to compensate 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?

States a verb and resource ('Search' + implied notes) and names the query dialect (Anki syntax), which is more than a tautology. But it does not differentiate this from siblings like preview_notes, which plausibly also searches notes, leaving ambiguity about which one an agent should pick.

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, when-not-to-use, or alternatives are mentioned. The agent gets no signal about search_notes vs preview_notes vs list_note_types for a given lookup intent.

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 the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) by disclosing atomicity, undoability, that IDs/tags/scheduling are preserved, that stale expected_fields abort the batch, and that identical arguments can be retried after a timeout. These are exactly the mutation-behavior facts the annotations cannot convey, and they are consistent with them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded and dense with no filler; the count bound, prerequisites and concurrency rule each get a clause. The telegraphic sentence fragments ('First inspect search_notes.') trade a little clarity for compactness.

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 described. For a batch mutation tool the description still covers authorization, preconditions, protected fields, atomicity, undo, ID/tag/scheduling preservation, stale-state aborts and retry behavior — nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden: it explains that fields are plain-text non-first fields, that expected_fields must match exact current HTML, and that batching is 1-100 notes. Only note_id's role in the nested object is left implicit.

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 ('edit 1-100 existing notes in place') with scope, batch bounds and in-place semantics. It is clearly distinguished from the create/search siblings by naming search_notes as the prerequisite inspection step and by excluding first/card-generating fields.

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 preconditions: user authorization, inspect search_notes first, and no first/card-generating fields. It does not route the agent between this and other mutation siblings like preview_notes or create_notes, so it stops short of full alternative coverage.

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