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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, so the description correctly does not restate that. It goes further and adds what the annotations cannot: the enumeration of failure conditions (missing deck/model, wrong field name, empty first field, duplicate note) and the atomicity guarantee that media failures occur 'before creating anything'. It does not cover partial-success or duplicate-detection semantics in depth, keeping it just short of 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?

Front-loaded with the action, then return value, then failure modes, then routing tips, then media semantics – a sensible ordering with no filler sentences. It is dense but every clause carries information; only the media sentence runs slightly long relative to the rest.

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 7-parameter write tool with nested media objects and no output schema, the description covers what is created, the return value (note ID), all failure modes, atomicity, and sibling routing. An agent has everything needed to invoke it correctly and interpret failures without opening anything else.

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 baseline is 3, but the description adds cross-parameter behavior the schema cannot convey: media `source` values are constrained to an http(s) URL or an absolute path on the machine running Anki, and each file is appended to the listed fields rather than replacing them. That framing meaningfully informs how to populate `picture`/`audio`/`video` and `fields` together.

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?

Opens with a specific verb+resource ('Creates one note in the given deck using the given model') and explains the downstream effect (Anki generates one or more cards) plus the return value (new note ID). It is clearly differentiated from the sibling add_notes ('for several notes prefer add_notes') and can_add_notes ('check with can_add_notes first').

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?

Names both alternatives explicitly and gives the condition that selects each: can_add_notes for a pre-flight check, add_notes when adding several notes. It also states the precondition that deck and model must already exist, leaving little inference to the agent.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), it discloses the failure model that matters most: partial success with null entries positionally aligned to the input, and the reasons a note can fail (duplicate, empty first field). It also states atomicity per note — if an attached file cannot be stored, that note is not created — and gives the error addressing format (notes[2].picture[0]).

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

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

Three sentences, front-loaded with purpose, then return shape, then the pre-validation pointer and the atomicity caveat. Every sentence carries distinct information with no repetition of the title or 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?

There is no output schema, so the description must explain return values — and it does precisely (ordered array of IDs, null for failures). With batch atomicity, error addressing, and the pre-check tool all covered, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning about how the single `notes` parameter behaves: results are order-aligned, and a null entry signals rejection of that element rather than a call failure. That is semantics the schema cannot express.

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 sentence gives a specific verb and resource plus the defining scope: "Creates several notes in one call." The batch framing distinguishes it from the singular add_note sibling without the agent needing to open 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?

It gives an explicit precondition — "Run can_add_notes first to find out which notes will fail" — naming a concrete sibling to call beforehand. What it leaves implicit is the routing decision for the single-note case (add_note) and whether validation is mandatory or merely recommended.

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 non-readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavior: the return value ("Returns null on success"), which matters because there is no output schema.

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

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

Three short sentences, each earning its place: purpose, ID-type constraint, tag format, and return value. The most failure-prone detail (notes vs cards) 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?

For a two-parameter mutation with annotations and no output schema, the description covers the return value, the input format, and the ID source. Minor gap: it doesn't say whether existing tags are preserved or how duplicate tags are handled, though idempotentHint implies the latter.

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% and both parameters are already documented there, including the space-separated format and the note-vs-card warning. The description largely restates the schema's tag format example rather than adding new semantics, so baseline 3 applies.

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

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

States a specific verb and resource ("Adds tags to notes") and immediately disambiguates the resource type with "takes note IDs, not card IDs", which separates it from card-oriented siblings like find_cards and from remove_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?

Gives the key selection constraint (note IDs, not card IDs) and the schema points to find_notes / cards_to_notes as ID sources. It does not explicitly contrast with remove_tags or explain when tagging is preferable to updating a note, so it stops 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, idempotentHint and destructiveHint=false, so safety is covered. The description still earns credit by specifying the return type/ordering and by stating a real scheduling rule (learning cards with intervals over 20 minutes are not due until that time elapses), which is behavior an agent cannot get from the annotations or schema.

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

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

Two short sentences, no filler. The return contract is front-loaded and the qualifying scheduling rule follows it, so a reader gets the essential fact first.

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 no output schema, the description usefully covers the return value and order, which is the main thing an agent needs. It is slightly incomplete on what 'due' means for non-learning card states (review/relearning cards) beyond the 20-minute learning-card rule.

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% and the parameter already documents card-vs-note IDs plus its source tools. The description adds only 'same order as input' for the response mapping, so this is the baseline case where the schema does nearly all the work.

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

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

The description names the exact resource (cards) and the exact question it answers (due for review now), plus the return shape (array of booleans in input order). That is enough to separate it from siblings like are_suspended and get_intervals without opening their schemas, though it never names those siblings 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?

Usage is only implied: an agent can infer this is a pre-review eligibility check and that are_suspended/get_intervals answer different questions. There is no explicit when-to-use or when-not-to-use statement, and no guidance on pairing it with find_cards to obtain IDs.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are positionally aligned with the input array and unknown card IDs yield null instead of an error, which tells the agent how to handle bad input. It stops short of any limits or bulk-failure behavior, so a 4 rather than 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?

One sentence, zero filler, and the most important fact (what comes back) is front-loaded. Nothing redundant with the title or annotations is restated.

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

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

For a single-parameter read-only predicate check with no output schema, the description supplies the return type, ordering guarantee, and unknown-ID handling. There is nothing else an agent needs in order to call this correctly.

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

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

Schema description coverage is 100% and the schema field already warns 'card IDs, not note IDs; get them from find_cards or notes_info.' The description adds only the input-to-output positional mapping ('same order as input'), which is helpful but thin; the baseline 3 applies when the schema carries the parameter burden.

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

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

The description states a specific verb and resource ('Returns an array of booleans ... telling whether each card is suspended') and immediately pins down the return semantics (order-preserving, null for unknown IDs). It implicitly separates this read-only check from the mutating siblings suspend/unsuspend, so an agent can pick correctly 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?

Usage is implied by the purpose: query suspension state for a batch of card IDs. There is no explicit when-to-use/when-not guidance, no mention of when to prefer a per-card check, and no stated batch-size or rate considerations. Adequate for a trivial query but nothing more.

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 read-only, idempotent, and non-destructive annotations, it discloses the result shape, positional correspondence with inputs, and common causes of false: duplicates, an empty first field, or an unknown deck/model. "Does not change anything" reinforces the annotations, and the return-behavior details are especially valuable because there is no output schema.

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

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

Three compact sentences front-load the relationship to add_notes, then explain results, common failures, and non-mutation. There is no filler or unnecessary recitation of the input 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 single-argument validation tool with a rich input schema and clear safety annotations, the description supplies the missing output contract and practical interpretation of false. The word "usually" appropriately signals that the listed failure causes are non-exhaustive, and no material invocation detail appears 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 fully documents the notes argument and its nested fields. The description adds useful validation semantics not captured there, particularly per-input result ordering and failure conditions involving duplicates, the first field, and deck/model validity.

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 identifies the operation as a dry run for the sibling add_notes tool, making clear that it checks creatability rather than creating notes. The per-note boolean result and input-order mapping make the purpose 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 for add_notes" provides clear preflight-validation context and distinguishes this tool from performing the actual addition. However, it does not explicitly say when to run this check or when calling add_notes directly is appropriate.

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 cover read-only, idempotent, non-destructive semantics, so the description is free to add real value: unknown IDs return empty objects, rendered HTML has CSS stripped, and output volume is large. The trailing 'and more' leaves the return surface slightly open-ended.

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 operation, then the field list, then two short operational notes; nothing is wasted. The long enumeration plus 'and more' is slightly loose but justified by the absence of an output 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?

No output schema exists, so the field enumeration serves as a partial return-value spec, and empty-result behavior is disclosed. Missing: whether 'fields' is a mapping, what HTML rendering implies, and anything on output size limits beyond a soft warning.

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

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

Schema coverage is 100% and already says IDs are card IDs not note IDs, but the description adds a reasoned constraint (keep the list short because output is large) that shapes how the agent batches the single array parameter.

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+resource ('Returns details for the given card IDs') and enumerates the returned fields (note, deckName, modelName, fields, interval, due, queue, reps), which clearly separates it from sibling find_cards that produces IDs in the first place. It stops short of explicitly naming the sibling boundary, so a 4 rather than a 5.

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?

Offers one practical directive ('Keep the ID list short; the output is large') and the schema points to find_cards/notes_info for obtaining IDs, but the description itself never states when to call this instead of find_cards or cards_to_notes.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description still adds real value by disclosing output cardinality (deduplicated unique note IDs, several cards per note), which is not derivable from the annotations. It stops short of stating ordering or response 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?

Two sentences, front-loaded with the return value, then the call-site guidance. No filler and no repetition of the title.

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

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

For a single-parameter read-only conversion tool with full annotation coverage, the description supplies enough to call it correctly. The only minor gap is that with no output schema it could have stated the return shape explicitly (an array of note IDs) rather than only 'Returns the unique note IDs'.

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

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

Schema coverage is 100% and the schema description already warns 'card IDs, not note IDs; get them from find_cards or notes_info'. The description adds no syntax, batching or size limits beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific transformation: it returns the unique note IDs that a set of card IDs belong to. The parenthetical 'one note can have several cards' explains the mapping's cardinality, which distinguishes it from lookup tools like cards_info and find_cards.

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

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

Explicitly says to call it 'before note tools such as add_tags or update_note_fields when you only have card IDs', naming concrete downstream consumers. It does not state the inverse (e.g., use find_cards/notes_info when you already have note IDs), but the 'only have card IDs' condition effectively implies the boundary.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds concrete substance on top: the cards leave their current decks and 'the previous placement is lost', plus the create-if-missing side effect and 'Returns null on success'. It stops short of describing failure or partial-failure behavior, so it is strong but not exhaustive.

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 semicolon-joined clauses plus a return-value note, all of which carry information; the destructive consequence is front-loaded right after the action. The 'card IDs, not note IDs' phrase is duplicated from the schema, a minor redundancy, but nothing else is wasted.

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

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

With only two required parameters, full schema coverage, and no output schema, the description covers action, ID type, deck-creation behavior, the destructive consequence, and the return value. Nothing an agent needs in order to invoke this 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 100%, so both parameters are already documented, including the 'Parent::Child' subdeck syntax and the card-vs-note ID distinction. The description restates the card-ID constraint rather than adding new parameter meaning, so the baseline 3 applies.

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

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

The description gives a specific verb and resource ('Moves cards ... to the given deck') and pre-empts the most likely confusion by stating 'card IDs, not note IDs'. It does not name or contrast with any sibling tool, but no sibling performs an overlapping move operation, so disambiguation is effectively complete.

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 clearly establishes the situation for use (relocating cards by card ID to a deck) and discloses the side effect that the target deck is auto-created, which is a real decision factor for the caller. It offers no explicit exclusions or alternative tools, but there is no competing tool in the sibling list to route away from.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the notable disclosure that subdecks are rendered as "Parent::Child", which is real behavioral value, but says nothing about ordering, filtering, or whether filtered decks are included.

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 return semantics front-loaded and the usage hint following. Every clause carries 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?

With no output schema, the description carries the burden of describing the return value and does so with the name-list plus subdeck separator detail. Minor gaps remain around ordering and edge cases, but nothing blocks correct invocation.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The mention of subdeck formatting pertains to output, not input, and is still useful.

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 ('Returns the names of all decks') and clarifies the output form, so an agent can contrast it with siblings like deck_names_and_ids or get_decks that carry ids or full objects. It doesn't name those siblings explicitly, which keeps it short of a 5.

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 usage context: get exact deck names before add_note or before searching with the deck: filter. That is a clear when-to-use hook, though it offers no explicit when-not or naming of the alternative lookup tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds the return structure, but says nothing about ordering, whether subdeck names are fully qualified with '::', or whether names can collide.

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 that names the return shape and contains no filler. Every clause carries 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 zero-parameter read tool with no output schema, the description supplies the essential missing piece, namely what is returned. It is only slightly short of complete because it omits how sibling listing tools differ and any note on deck-name qualification.

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 for the description to disambiguate and no schema gap to compensate for. Baseline 4 applies; the description correctly does not invent parameter discussion.

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 and, unusually, also states the return shape: an object mapping deck name to deck ID. It does not distinguish this from the sibling tools deck_names and get_decks, which likely overlap, so the agent must guess which of the three to 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?

There is no when-to-use guidance and no mention of the alternatives deck_names, get_decks, or model_names_and_ids, which appear to cover similar ground. The agent is left to infer whether this is the cheap name-to-ID lookup versus a full deck-object fetch.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true), the description discloses exactly what gets destroyed (every card when cardsToo=true), that it is irreversible through this API, the version-dependent cardsToo requirement, and the null return on success. That is precisely the extra context annotations cannot convey.

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

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

Five short sentences, each earning its place, with the core action front-loaded and the destructive warning immediately after. No filler or restatement of the title.

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

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

For a two-parameter destructive tool with no output schema, the description covers action, danger, irreversibility, version constraints, user confirmation, and the return value. Nothing an agent needs in order to call it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains the destructive consequence of cardsToo=true and the important constraint that recent versions require it. That goes materially beyond the schema's one-line "true deletes the cards in those decks as well."

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

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

The description opens with a specific verb+resource ("Deletes decks by name") and immediately clarifies scope via the cardsToo warning, so it is clearly distinguishable from read-side siblings like deck_names, get_decks, and change_deck. It stops short of explicitly naming a sibling, which keeps it at 4 rather than 5.

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 call-time guidance: confirm with the user first, and note that recent AnkiConnect versions require cardsToo=true and refuse otherwise. It does not discuss alternatives or non-deletion paths, but none of the listed siblings offer a safer substitute, so the practical guidance is essentially 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the description earns credit for going further: it clarifies that the file goes to the trash (implying recoverability), describes the user-visible consequence on cards, and states the return value. It omits edge behavior such as what happens when the filename does not exist or whether an error is raised.

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 actual behavior, then consequence, then the confirmation rule and return value. Every sentence adds information and none repeats the title 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 one-parameter destructive tool with no output schema, the description covers what it does, the side effect, the safety check, and the null return. The only missing piece is failure behavior for a nonexistent filename, a minor but real 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 100% and the single parameter already carries a description ('File name in the media folder'), so the schema does the heavy lifting. The phrase 'a file that notes may use' hints at the referential relationship but adds no format, path, or extension detail beyond 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?

The description gives a specific verb and resource ('Moves a file from Anki's media folder to the trash'), which is far more precise than the title's bare 'Delete'. It is implicitly distinguishable from siblings like store_media_file and retrieve_media_file, but it never names them explicitly, 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?

It supplies a real usage precondition: 'Confirm with the user before deleting a file that notes may use,' which tells the agent when to pause and check rather than fire immediately. It offers no explicit when-not guidance or named alternative (e.g. checking get_media_files_names first), which keeps it below a 5.

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, idempotent, non-destructive semantics, so the bar is lower, but the description adds real behavior: the exact return shape (ids/total/truncated), the default limit of 100, and what truncation means. It does not state whether queries are case-sensitive or how pagination beyond the limit works, keeping it short of 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 tight sentences, zero redundancy: identity and return type first, response shape second, routing advice last. Every clause carries information the 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?

Despite having no output schema, the description fully specifies the response envelope, and for a two-parameter read-only search tool nothing essential is missing. The sibling routing covers the main risk of misuse.

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%, establishing a baseline of 3, but the description adds intent beyond the schema by explaining that the default limit is 100 and why increasing it is usually the wrong fix. This gives `limit` operational meaning (truncation driver) rather than just a number bound.

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 ("Searches cards with Anki search syntax") and explicitly scopes the return to CARD IDs, immediately distinguishing it from find_notes which returns note IDs. An agent can pick between the two without inspecting 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?

Names two alternatives with conditions: use find_notes when you need note IDs, and pass results to cards_info for details. It also gives a strategic rule — narrow the query rather than raise the limit — which tells the agent how to behave when results are truncated.

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, idempotentHint and non-destructive behavior, so the safety profile is covered. The description adds real behavioral detail beyond that: truncation semantics ("whether the list was cut"), the default cap of 100, and the advisory to narrow queries instead of raising limits. It stops short of describing error or empty-result behavior, so not 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?

Front-loaded with the verb and the key ID-type distinction, then the return contract, then usage advice — a sensible priority order with no filler. It is dense (parentheticals and a JSON-shaped return sketch in one paragraph) but every clause carries 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?

There is no output schema, so the description carries the return-value burden itself and does so precisely: an ids array, a total, and a truncated flag. Combined with the sibling routing and the limit guidance, an agent has everything needed to call this correctly and chain it into notes_info.

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

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

Schema coverage is 100%, so both parameters are already documented, making 3 the baseline. The description earns above baseline by framing `limit` in operational terms (default 100, results may be truncated) and by advising query narrowing as the preferred alternative to raising the limit.

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 ("Searches notes with Anki search syntax") and immediately disambiguates the returned entity: "returns NOTE IDs (use find_cards for card IDs)". That contrast with a real sibling makes the tool's identity unmistakable 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 explicit routing rules: use find_cards when you want card IDs, pass results to notes_info for details, and prefer narrowing the query over raising the limit. Both the downstream alternative and a usage constraint are spelled out rather than implied.

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, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds value beyond them by disclosing the actual payload shape, notably that the options group carries a config `id` usable downstream. It stops short of stating error behavior for a nonexistent deck.

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 sentence that front-loads the action and resource, then enumerates the return contents without filler. Every clause earns its place by telling the agent what it will receive.

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 no output schema, the description must carry return-value information, and it does so by listing the settings the config contains plus the `id`. For a single-parameter, annotated read tool this is nearly complete; only failure behavior for an invalid deck name 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?

There is a single parameter with 100% schema description coverage ('Deck name.'), so the schema already carries the semantics and the baseline is 3. The description only refers to 'the given deck' and adds no format, case-sensitivity, or resolution details beyond 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?

Names a specific verb and resource ('Returns the options group used by the given deck') and enumerates the returned content: new card/review limits, learning steps, lapse settings, and config `id`. No sibling tool returns deck configuration, so an agent can distinguish it from deck_names/get_decks 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?

Usage is only implied: an agent infers 'use this when you need the current options for a specific deck.' There is no explicit statement about when not to use it, no mention of the alternative ways to enumerate decks (deck_names, get_decks), and no guidance on what happens if the deck name is unknown.

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, idempotent, and non-destructive behavior, so the safety profile needs no restating. The description does add the useful fact that the result is an object keyed by deck name whose values are the matching card IDs, which matters because there is no output schema. It says nothing about how cards in multiple decks or unknown card IDs are handled.

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 sentence containing the input constraint, the operation, and the return shape, with nothing extraneous. The closing clause 'the given card IDs that are in it' is slightly tangled, which keeps it from a perfect score.

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

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

A one-parameter read tool with full schema coverage and no output schema, and the description covers both the disambiguation (card vs note IDs) and the shape of the response. It is close to complete, missing only edge-case behavior for nonexistent or multi-deck cards.

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

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

Schema coverage is 100% and the single parameter already documents 'card IDs, not note IDs; get them from find_cards or notes_info.' The description repeats the card-vs-note distinction without adding format, ordering, or size-limit detail beyond the schema, so the baseline 3 applies.

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

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

States a specific operation: given card IDs, return a mapping of deck name to the card IDs contained in each. This clearly distinguishes it from siblings like deck_names (lists name/ID pairs) or find_cards (searches cards). It does not explicitly name a sibling, keeping it just below a 5.

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 — supply card IDs, learn which decks own them — and the 'not note IDs' parenthetical warns against a common input mistake. However, there is no explicit when-to-use or when-not-to-use guidance relative to alternatives such as cards_info or change_deck.

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 that this is a safe, idempotent, closed-world read, so the bar is lower. The description still adds real value the annotations do not: output ordering mirrors the input, intervals are signed with negative meaning seconds and positive meaning days, and complete controls whether arrays of history or a single latest value come back.

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 with no waste, front-loaded with the core purpose and ordering guarantee, followed by the unit convention and the mode toggle. Nothing is repeated unnecessarily.

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?

There is no output schema, so the description must carry return semantics, and it covers ordering, units, and the shape difference between modes. It stops short of clarifying edge cases such as cards with no review history or whether new cards yield zero/absent intervals, which would fully close the gap for a two-parameter read 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 100%, so the schema already documents both cards and complete, including the false/omitted case. The description largely restates the complete flag, adding only that full history is returned 'as arrays'; the sign/unit rule describes return values rather than parameter meaning.

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 specific verb and resource ('Returns review intervals per card') and adds discriminating detail: result order matches the input, and units depend on sign. That is enough to separate it from neighbors such as cards_info or are_due, though no sibling is named 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?

Usage is only implied: an agent can infer you call this when you need scheduling intervals for known card IDs. There is no statement of when to prefer cards_info or are_due instead, and no prerequisites or exclusions are given; the complete flag is explained as behavior rather than as a usage decision.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them by naming the concrete folder ('collection.media') and stressing that the path is on the computer running Anki — a meaningful caveat for a remote client, which would receive the server's filesystem path rather than its own.

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 filler, front-loading the return value and then qualifying it with the folder name and host machine. 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 zero-parameter, read-only lookup with no output schema, the description carries the necessary burden by explaining exactly what string is returned. Minor gap: it does not say what happens if the media folder has not been created yet, or whether the path uses native separators.

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 for the description to disambiguate. Baseline of 4 applies; the description correctly avoids inventing parameter discussion for a no-argument 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 ('Returns') and an exact resource ('the absolute path of Anki's media folder (collection.media)'), and clarifies the machine context. No sibling tool returns a folder path — the others operate on media file names, contents, or deletion — so the agent can distinguish this 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?

Usage is implied by the narrow purpose: an agent needs it when constructing or displaying an on-disk path to media assets. There is no explicit when-to-use statement, no mention of alternatives such as get_media_files_names, and no note about prerequisites (e.g., whether the media folder must already exist).

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that by disclosing the result envelope (names/total/truncated), the default limit of 100, and the fact that results can be silently capped — a real behavioral trait the annotations do not 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?

Three tight sentences: what it does, what it returns with the cap caveat, then the intended use. The purpose is front-loaded and nothing is redundant 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 two-parameter read-only listing tool, the description covers the operation, the glob semantics, the result shape including the truncation flag, and the primary use case. With no output schema present, spelling out the return envelope is exactly the missing piece an agent would otherwise have to guess.

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 both `limit` (with its default and minimum) and `pattern` (with glob examples and its "*" default) are already fully documented in the schema. The description repeats the default limit of 100 and the pattern-matching idea without adding syntax or edge-case meaning, so baseline 3 applies.

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

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

The description states a specific verb and resource ("Lists file names in Anki's media folder") and narrows it with the glob filter, which cleanly separates it from siblings like retrieve_media_file or store_media_file that move file contents. It never names an alternative explicitly, so it falls just 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?

"Use it to check whether a file already exists" gives a concrete when-to-use scenario rather than leaving usage implied. It does not say when not to use it or point to a specific alternative such as retrieve_media_file for fetching contents, so no exclusions are provided.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral information: the result is a flat array of strings covering "every tag used," which tells the agent there is no filtering, pagination, or per-note breakdown.

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. The scope ("every tag used in the collection") and the return shape are packed into one clause each, with nothing redundant.

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 no-argument listing tool with no output schema, the description supplies the one thing structured data lacks: the return format. It stops short of stating ordering or whether tags defined but unused are excluded — "used in the collection" hints at the latter but doesn't settle it.

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?

There are zero parameters, so the baseline is 4. Nothing about argument meaning needs explaining, and the description correctly implies the tool takes no input.

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 ("Returns every tag used in the collection") and even the return type ("array of strings"), so an agent knows exactly what it produces. It does not explicitly distinguish itself from siblings such as add_tags or remove_tags, though the name and phrasing make the read-only listing role obvious.

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: an agent can infer this is the tool to enumerate available tags before calling add_tags or remove_tags, but the description never says when to use it or names an alternative. No prerequisites, no exclusions, no note about collection scoping being implicit.

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, idempotent, non-destructive. The description adds real behavioral value beyond them: the names are returned in order, and the first field has a non-empty constraint that matters for downstream note creation. It does not discuss error behavior for an invalid model name, which the openWorldHint=false makes worth mentioning.

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: the return value and example come first, then the downstream constraint. 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, and the description fully compensates by describing the return shape and ordering plus an example. For a one-parameter read tool with rich annotations, nothing required 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?

Schema description coverage is 100% and the single parameter is already documented, including the pointer to model_names. The description only refers to "the given model" without adding format or exactness guidance, so it matches the baseline rather than extending it.

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

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

States a specific verb and resource ("Returns the field names of the given model") and includes a concrete output example ["Front", "Back"], which implicitly distinguishes it from model_names and model_fields_on_templates. An agent can tell what it gets without opening the schema.

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

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

Explicitly tells the agent how to consume the result: use these exact names as keys of `fields` in add_note/add_notes, and that the first field must not be empty. It does not state when to prefer model_fields_on_templates instead, so sibling routing is only partially covered.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond them by specifying the exact return shape ({"Card 1": [["Front"], ["Back"]]}), which matters because no output schema exists. It does not say what happens for a model with no templates or an unknown model name.

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 result and then exemplifies its structure. Every clause earns its place, with no preamble or redundant restatement of the title.

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

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

For a single-parameter read tool with full schema coverage and no output schema, the description gives the essential missing piece: the return shape. Only edge cases (unknown model, model without templates) are left unaddressed.

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

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

Schema coverage is 100%: the single modelName parameter is already documented with an example ("Basic") and a pointer to model_names. The description adds no further meaning about the parameter, so the baseline 3 applies.

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

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

States a specific verb and resource: it returns, per card template of a model, which fields appear on front and back. That is clear enough to distinguish it from model_field_names (field names of the model) and model_names (model list), though it never names those siblings 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?

Usage is only implied by the description and the title: you would call it when you need to know template front/back field composition. There is no statement of when to prefer this over model_field_names, nor any note about preconditions such as the model having templates.

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, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered elsewhere. The description's only added context is what the returned values look like, which is modest but useful for interpreting 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?

A single front-loaded sentence with no padding. The nested quoted examples make the phrasing slightly fussy, 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?

For a parameterless read that returns a flat list of names, the description plus annotations cover everything needed: what comes back, that it is safe and repeatable, and what the strings look like. No output schema exists, but the return value is described sufficiently.

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 for the description to disambiguate and the baseline is 4. No parameter meaning is missing because none exists.

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 ('returns the names of all models') and clarifies the domain-specific synonym by equating models with note types, plus concrete example values. It does not distinguish itself from the sibling model_names_and_ids, which a caller could easily confuse it with.

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 explicit when-to-use guidance and no mention of alternatives such as model_names_and_ids for callers who need IDs as well as names. Usage is only implied by the nature of the return value.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine value by disclosing the return shape (a name→ID object) and the completeness guarantee ('every model'), which matters because no output schema exists. It says nothing about ordering or how large the set may be.

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 leads with the return type and delivers the key distinction (IDs, not just names) with zero filler. No redundancy against the title, which only says 'List note types with IDs'.

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-param, read-only listing tool with no output schema, the description supplies the essential missing piece: the return structure. What is absent is routing guidance relative to the very similar sibling model_names, which leaves a small but real 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?

The tool takes zero parameters, so the baseline is 4 and there is no input semantics for the description to compensate for. Nothing in the description misrepresents the (empty) input contract.

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 ('Returns') and resource ('an object mapping every model (note type) name to its model ID'), and the parenthetical resolves the model/note-type terminology an agent may not know. It implicitly separates itself from sibling model_names by including the ID, though it never names that 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?

Usage is only implied: an agent can infer it should call this when it needs the numeric model ID rather than just names. There is no explicit when-to-use statement, no exclusion, and no pointer to model_names for the names-only case.

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 read-only, idempotent, non-destructive behavior, so the description needn't restate safety. It adds two genuinely new facts: the exact shape of the returned records (including per-field value and order, plus generated card IDs) and that unknown IDs yield empty objects rather than errors, which is exactly the kind of edge-case an agent needs.

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

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

A single compact sentence front-loads the action and return payload, then closes with the unknown-ID behavior. No filler and nothing repeated from annotations or 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?

With no output schema, the description carries the burden of describing returns and does so field by field, plus the not-found behavior, which is sufficient for a one-parameter read tool. Minor gaps remain around batch limits and result ordering relative to the input array.

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

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

Schema coverage is 100% and the schema description already spells out that these are note IDs, not card IDs, and where to source them. The description adds no format or batching detail beyond what the schema provides, so baseline 3 applies.

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

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

States a clear verb and resource ("Returns details for the given note IDs") and enumerates the returned fields, which separates it from list-style siblings like find_notes. It does not explicitly contrast with cards_info or cards_to_notes, but the note-vs-card distinction is implied by the field list.

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

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

No when-to-use or when-not-to-use guidance appears in the description. The useful routing hint (get IDs from find_notes or cards_to_notes) lives only in the schema, so the description itself never tells an agent how to obtain inputs or when to prefer cards_info instead.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered structurally. The description's real contribution is 'Returns null on success', which substitutes for the missing output schema. It does not say what happens when a tag is absent from a note or when a note ID is invalid, which matters for a destructive 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?

Three short sentences, zero filler, with the most error-prone detail (note IDs, not card IDs) front-loaded. Every sentence carries information an agent would otherwise get wrong.

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 destructive mutation with rich annotations and no output schema, the definition covers identity, ID type, tag format, and return value. It falls short only on partial-failure semantics (tag not present, unknown note ID), which an agent would benefit from knowing before calling.

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% and both parameters are fully documented in the schema, including the space-separated format and the note-ID sourcing hint. The description restates the tags string format rather than adding new meaning, so 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?

Names a specific verb and resource (remove tags from notes) and immediately disambiguates the entity type with 'takes note IDs, not card IDs'. That distinction separates it from the card-oriented siblings (find_cards, cards_info, cards_to_notes) and from add_tags 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?

The use case is implied by the verb and the note-ID caveat, but there is no explicit statement of when to prefer this over add_tags or update_note_fields, and no guidance on prerequisites, error conditions, or whether a note must already carry the tag. Usage is inferable 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the polymorphic return contract: PNG/JPEG/GIF/WebP up to 5 MB come back as viewable images, everything else returns {filename, bytes}. It also names the failure condition for missing files, which is exactly the behavioral context annotations cannot convey.

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

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

Three short sentences, front-loaded with the core action, then the return branching, then the error condition. Nothing is redundant and every sentence adds information an agent needs before calling.

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

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

There is no output schema, so the description must explain return values itself, and it does so precisely with the MIME/size branching. For a one-parameter read tool with full annotation coverage, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single filename parameter is already documented as 'File name in the media folder.' The description reinforces that the name refers to Anki's media folder but adds no format, extension, or path semantics, so the schema carries the load and the baseline 3 applies.

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

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

The description opens with a specific verb and resource: 'Returns a file from Anki's media folder.' The return-mode details (images inline vs. {filename, bytes}) make it unambiguous that this fetches file content, which distinguishes it from get_media_files_names (listing) and store_media_file (writing).

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 rather than stated: the agent can infer you call this with a filename to fetch content, and the 'Fails if the file does not exist' note hints at a precondition. However, it never names alternatives such as get_media_files_names for discovering valid filenames, and gives no explicit when-not-to-use 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=false, destructiveHint=false, and idempotentHint=true; the description adds real context beyond them by stating 'Never overwrites an existing file' and that the stored name may be renamed. It also specifies the exact follow-up syntax (`<img src="NAME">`, `[sound:NAME]`), which is behavior an agent cannot infer from structured fields. Minor gap: no mention of size/type limits or failure modes.

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

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

Front-loads what it does and the returned-name caveat, then the usage guidance, in a compact sequence with no filler. It is dense but each sentence carries either routing or behavioral information; the imperative 'Never try to write out the bytes...' style is efficient rather than verbose.

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 no output schema, the description carries the return-value burden and does so fully: it explains that the returned NAME may differ and must be used verbatim, and shows the exact embedding syntax for images and audio. For a two-parameter write tool with full annotation coverage, nothing an agent needs is missing.

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

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

Schema coverage is 100%, and the schema descriptions already enumerate URL, absolute path, clipboard, and base64 data URL forms plus filename defaulting rules. The description only restates the clipboard option, so it adds little beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Stores a file in Anki's media folder') plus the return semantics ('returns the name Anki stored it under, which can differ'). It is clearly distinguishable from siblings like retrieve_media_file, get_media_files_names, and add_note, which is named 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?

Gives explicit routing: prefer the `picture`/`audio`/`video` params of add_note, add_notes, and update_note_fields when attaching media to a note, implying this tool is for standalone storage. It also documents the `source` = "clipboard" case for just-copied/pasted images, so when-to-use and when-not-to-use are both covered.

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 idempotent, non-destructive, non-read-only behavior, so the bar is lower. The description still adds real value: it discloses reversibility and, importantly, the return-value semantics (true if at least one card was not already suspended, false otherwise), which is genuine behavioral context not present in annotations.

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

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

Two short sentences, front-loaded with the action and effect, followed by the return contract. No filler or repetition of the title.

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

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

With one required parameter, full schema coverage, and explicit annotations, the description covers purpose, reversibility, and the return value despite there being no output schema. It could go slightly further on batch edge cases (invalid or unknown card IDs), but nothing essential is missing.

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

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

Schema coverage is 100% and the schema itself already warns that these are card IDs rather than note IDs and points to find_cards/notes_info. The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific verb and resource ("Suspends cards") plus the concrete effect ("not shown in reviews"), which immediately separates it from sibling tools like unsuspend and are_suspended.

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 the stated effect and the parenthetical pointer to unsuspend for reversal, but there is no explicit when-to-use or when-not-to-use guidance, nor any routing advice versus sibling tools such as are_suspended or change_deck.

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=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavior beyond them: the boolean return semantics (true only if at least one card was previously suspended). It leaves open how nonexistent or already-active card IDs are handled.

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 effect, followed by the return-value contract. No wasted wording and nothing buried.

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, idempotent, non-destructive mutation with full schema coverage and annotations, the description covers effect and return value. Only edge-case behavior for invalid or already-unsuspended IDs is unstated, which is a minor 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 description coverage is 100% and the parameter already spells out that these are card IDs, not note IDs, and where to get them. The description adds no further meaning about the cards array, so the schema does all the work — the baseline 3 applies.

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

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

States a specific verb and resource ("Unsuspends cards") plus the effect ("return to reviews"), which makes it unambiguously the inverse of the sibling suspend tool. It does not name that sibling explicitly, so it stops short of full 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 purpose implies when to use it — cards that are suspended and should re-enter reviews — but there is no explicit when/when-not guidance and no mention of the alternatives (e.g. suspend, are_suspended) for checking state first. Usage is inferable rather than stated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description still adds real value beyond them: fields not listed are preserved, previous values are irrecoverably lost, success returns null, and media is appended rather than replacing the field. That is solid supplementary disclosure but not exhaustive (no permission or failure behavior).

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 sentences, each earning its place: the destructive-overwrite warning and the notes_info prerequisite are front-loaded, and the media-append rule comes last. No restatement of the name or 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?

Despite no output schema, the description explicitly states the return value (null on success), and covers the destructive nature, the partial-update semantics, and the non-obvious media append behavior for a 5-parameter nested tool. An agent has everything needed to 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% and the nested source/filename/fields descriptions are already rich, so the baseline is 3. The description adds genuine meaning about interaction between parameters — that media attaches to the new value or, if the field isn't overwritten, the current one — which goes beyond the schema's per-parameter text.

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 ('Overwrites the given fields of an existing note') and adds a disambiguating parenthetical that the ID is a note ID, not a card ID. That directly separates it from card-oriented siblings like cards_info or suspend.

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 concrete prerequisite workflow — read the note with notes_info first if you need the previous values — and tells the agent to omit fields when only attaching media. It does not name an alternative for creation (add_note) or state when not to use this tool, so it stops 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 readOnly, idempotent, non-destructive and non-open-world, so safety is covered. The description adds value by framing the call as a lightweight health check and indicating the shape of a successful return; it does not say what happens on failure, but the "check that Anki is running" framing implies an error surfaces when unreachable.

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

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

Two short sentences with zero filler: the first says what it returns, the second says why you'd call it. Front-loaded and immediately actionable.

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 trivial zero-parameter probe, the description supplies purpose, return type with example, and intended use. No output schema exists, but the example value effectively conveys the return.

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. There is nothing for the description to disambiguate beyond what the empty schema already conveys.

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 ("Returns the AnkiConnect API version number") and includes a concrete example value ("e.g. 6"). This is unmistakably different from data-oriented siblings such as deck_names or notes_info.

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 clear context for use: a cheap connectivity/liveness probe to confirm Anki is running and reachable. It does not name exclusions or alternatives, but no sibling overlaps this purpose, so the omission is minor.

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