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

Annotations already declare non-read-only, non-idempotent, non-destructive, and open-world, so the description's only added value is 'Returns the new Card.' Critically, it does not explain the add-vs-update decision, whether calling twice creates duplicates (idempotentHint=false makes this a real risk), or how fields map when a notetype differs.

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 purpose, no filler prose. The 'plus 2 more' truncation is the one wasted element—listing back and tags would have cost no more space.

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 mutating, non-idempotent creation tool with no output schema and zero required parameters, the description should cover duplicate risk, which fields are meaningful per notetype, and what 'update' targets. None of that is present, leaving an agent likely to call with only a front field and no understanding of the resulting note.

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 per-property descriptions already carry the semantics; baseline is 3. The description's parameter mention ('deck, notetype, front (plus 2 more)') is vague and omits that all parameters are optional and that notetype defaults to Basic.

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

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

States a verb (add/update) and resource (note/card in AnkiWeb collection), which is enough to place it against read-only siblings like card_get or card_search. But 'update' is unclear: the schema has no card/note identifier, so an agent cannot tell how an existing card would be targeted. The 'plus 2 more' phrasing is a hedge rather than a specification.

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 guidance, no exclusions, and no reference to alternatives such as card_import (bulk) or card_search/card_get (read paths). The agent must infer that this is the single-card creation path from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered and the description adds nothing further. It does not say what a result looks like, how duplicates are grouped, or how the live/local data-source behavior affects detection, which matters for a 23-flag tool.

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

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

A single front-loaded sentence with zero filler; the resource and scope appear immediately. It is efficient, though so terse that it leaves the heavy lifting entirely to structured fields.

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

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

With 23 parameters, no output schema, and an undefined term ('colliding prompts'), the description should explain what is returned and what constitutes a duplicate. Nothing about output shape, grouping, or the live/local read path is disclosed, leaving the agent guessing at results.

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 all 23 parameters are documented in the schema itself and the baseline of 3 applies. The description adds no parameter-level meaning, notably omitting the deck scoping filter that would be the most natural guidance to surface.

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 ('Detect') and resource ('duplicate notes and colliding prompts') with an explicit scope ('across decks in your collection'), which distinguishes it from sibling readers like card_search or card_get. It does not name any sibling explicitly, so it falls just 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?

There is no statement of when to run this versus alternatives such as card_search, sql, or deck_triage, nor any preconditions (e.g. sync state, whether local data is required). The only usage signal is the implicit 'collection-wide unless scoped' framing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered, but the description adds little beyond it. 'Returns the new Card' is confusing (a get returning something 'new'?) and it never says what happens when note_id is omitted, which is the key behavioral question for a zero-required-param tool.

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

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

Very short, but the final sentence ('Returns the new Card') is both vague and slightly contradictory in phrasing, so brevity comes at the cost of a wasted sentence.

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 burden of explaining return values, and 'Returns the new Card' is uninformative about shape or fields. The note-vs-card ambiguity and undocumented no-argument behavior leave real gaps for a tool an agent must call 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% for the single note_id parameter, so the schema does the documentation work. The description confirms note_id is optional but adds no format, semantics, or fallback behavior beyond that.

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 ('Get details and field values') but conflates the resources: the tool is card_get yet the description says it retrieves a 'note' and returns a 'Card', leaving the agent to guess the relationship. It never distinguishes itself from sibling tools like card_search or card_duplicates.

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

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

No statement of when to use this tool versus card_search, card_duplicates, or deck_list. The 'Optional: note_id' fragment hints at a no-argument mode but never explains when to use that mode or what it does.

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

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

Annotations declare destructiveHint=true and openWorldHint=true, so an agent knows this mutates state, yet the description says nothing about what is destroyed or created, duplicate handling, confirmation prompts, or rollback. Those details exist only as opaque flags (`yes`, `idempotent`, `dry-run`) in the schema, leaving the description to add almost nothing beyond annotations.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though for a 26-parameter destructive tool the brevity is arguably under-specification rather than optimal conciseness.

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

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

With 26 optional parameters, destructive semantics, and no output schema, an agent needs to know what the import produces (counts, errors, partial failures) and how to invoke it safely. The description covers none of this, leaving critical behavior to flag names alone.

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

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

Schema description coverage is 100%, so baseline 3 applies; every one of the 26 parameters is already documented in the schema. The description only implies `deck` and source-format semantics, adding no format syntax or naming conventions beyond the structured data.

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 ('Batch import flashcards') and enumerates the accepted source formats (Markdown files, Q&A blocks, cloze notes) plus the destination ('any deck'). It is clear on its own, but never names how it differs from the sibling `import` or `card_add`, which an agent would want to disambiguate.

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

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

There is no guidance on when to choose this over `card_add` (single card) or the generic `import` sibling, nor any mention of prerequisites such as confirmation handling or dry-run. The only usage signal is the implicit 'batch' qualifier.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the result spans the user's whole collection (both note types and decks), but says nothing about return shape, ordering, or how the two resource kinds are combined in one response — a real ambiguity for a tool that returns two entity types.

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 no filler, front-loading the verb and both returned resource kinds. Nothing could be removed without losing 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 and no parameters, the description carries the burden of explaining what comes back. It names the two entity types but leaves the structure of the combined response and any filtering/scoping behavior unstated, so it is adequate but thin.

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

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

The tool takes zero parameters, so there is no parameter semantics to document; the baseline of 4 applies. The description correctly implies no input is required.

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

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

The description gives a specific verb ('List') and two resources ('note types and decks'), and notably reveals that the tool returns decks as well as note types — information the name 'card_notetypes' does not convey. It does not, however, distinguish itself from the sibling deck_list, which appears to overlap on the decks portion.

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 guidance on when to call this versus deck_list or card_add, and no prerequisites stated (e.g., use before card_add to discover valid note type names). The agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered by structured data. The description adds only the return shape (array of Card) and says nothing about result limits, pagination, ordering, or cost of open-world queries — useful but thin extra context.

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

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

Three terse, front-loaded fragments with no filler; the core action comes first and the return type last. It is efficient, though the telegraphic style leaves gaps that a slightly longer sentence could have closed.

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 optional parameter, no output schema, and annotations covering safety, the description is adequate but not complete: it doesn't explain the notes/cards distinction, what an empty query returns, or whether results are truncated — all relevant for an open-world search tool.

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

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

Schema coverage is 100% and the schema itself documents `query` as "Anki search syntax", so the description's contribution is limited to restating that the parameter is optional. Baseline 3 applies when the schema does the heavy lifting.

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 ("Search notes in your collection") and names the return type ("array of Card"). However, it never distinguishes itself from the sibling tools `search`, `card_get`, or `card_duplicates`, and the notes-vs-cards wording is slightly inconsistent with the stated Card return type.

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?

"Optional: query" implies that an empty call lists everything, which is mild usage signal, but there is no statement of when to use this versus the sibling `search` tool or `card_get` for a direct lookup, and no exclusions or prerequisites.

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 disclose readOnly and openWorld. Description adds what the context contains but does not contradict 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 concise sentences, no wasted words. Front-loaded with action and resource.

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

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

Given zero parameters and no output schema, the description fully covers what the tool does and when to use 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?

No parameters exist; baseline 4 per instructions. Description adds no parameter info, but none needed.

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?

Clearly states the tool retrieves API domain context including specific items (resource taxonomy, auth requirements, etc.). Distinct from sibling action tools.

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

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

Explicitly says 'Call this first', providing clear temporal guidance. Does not explicitly name alternatives but context implies using siblings for subsequent actions.

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, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that it returns the new Deck, which is useful because no output schema exists, but it does not disclose duplicate-name behavior, permissions, or other side effects.

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

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

Three short sentences with zero waste. The core action and required parameter are front-loaded, and the return value is noted compactly.

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

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

For a simple one-parameter creation tool with full schema coverage and annotations, the description is nearly complete: it states the action, required input, and return object. A minor gap is the lack of any note on duplicate deck names or failure behavior.

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% for the single 'name' parameter, and the schema already documents it as 'Name of the new deck.' The description only restates that name is required, adding no format or constraint 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?

The description gives a clear verb and resource: 'Create a new deck in your collection.' This is unambiguous against siblings like deck_rename or deck_delete, though it does not explicitly name or distinguish alternatives.

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

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

It states the required parameter but gives no guidance on when to use this tool versus deck_rename, deck_delete, or other deck operations. The agent must infer the appropriate context from the tool name alone.

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

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

The description says 'Delete', which is inherently destructive, while annotations declare destructiveHint=false. It also omits important consequences such as whether deletion is permanent, what happens to cards in the deck, or whether confirmation is required.

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

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

Two short sentences with the action and required parameter front-loaded. There is no wasted text.

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 destructive operation with no output schema and contradictory annotations, the description is too thin. It does not explain side effects, reversibility, or permissions, leaving the agent without critical safety context.

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 as 'Deck ID to delete'. The description repeats that deck_id is required but adds no further semantic detail, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: delete a deck from the user's collection. It is immediately distinguishable from siblings like deck_create, deck_rename, and deck_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 guidance is given on when to use this tool versus alternatives, prerequisites, or when not to use it. The only instruction is the required deck_id parameter.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no indication of what the returned limits contain, whether limits are per-deck defaults or user overrides, or whether they are static or change with study progress.

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 resource. The second sentence is largely redundant with the schema's required array, costing a small amount of space for no new 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 single-parameter read tool with full schema coverage, annotations covering safety, and no output schema to explain, this is close to sufficient. The only gap is that an agent cannot anticipate what a 'limit' object looks like 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 coverage is 100%, so the single deck_id parameter is documented structurally. The description only repeats 'Required: deck_id' and adds no semantic detail such as how to obtain a deck ID or what an invalid one does; baseline 3 is appropriate when the schema does 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?

States a specific verb and resource: 'Get daily study and review limits for a deck.' An agent can tell this apart from deck_list or deck_rename without opening the schema, though it never names the sibling it complements or contrasts 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 when-to-use guidance, no prerequisite conditions, and no reference to alternatives (e.g., when to fetch limits versus calling study). The only guidance is a restatement of the required parameter.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds the return payload shape (array of Deck with three count fields), which is genuinely useful since no output schema exists, but says nothing about ordering, pagination, empty-state behavior, or the openWorldHint=true remote aspect.

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 operation and immediately followed by the return value. No filler, though the second sentence is slightly redundant with the first's mention of card counts.

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 this is close to sufficient, and the description does cover the return shape in lieu of an output schema. But the "Deck" object and the three count meanings are left undefined, and there is no guidance on when this beats sibling listing tools.

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 schema imposes no semantic burden and the baseline is 4. However, the description also introduces the returned fields "due, learn, and new" without defining them, which is where clarity is actually needed; that falls short of a full 4.

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

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

States a specific verb and resource ("List all decks") plus what each entry contains (due, learn, and new card counts), which is more informative than the bare name. It does not, however, distinguish itself from nearby siblings like deck_limits or deck_triage, leaving the agent to infer why one would list decks rather than query limits.

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 guidance, no prerequisites, and no mention of alternatives among a large sibling set (deck_limits, deck_triage, search, sql). The agent must derive the call context entirely on its own.

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

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

Annotations already declare write (readOnlyHint=false), non-destructive, and non-idempotent, so the main behavioral profile is covered. The description adds the return value ('Returns the new Deck'), which helps, but it does not address what happens when the deck does not exist, permission requirements, or whether renaming is reversible.

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

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

Three short sentences, front-loaded with the action and return value. The 'Required: deck_id, name' sentence duplicates the schema's required list and could be dropped, but the overall entry is tight.

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

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

For a simple two-parameter mutation with a clear return statement and annotations covering the safety profile, this is nearly complete. Missing only edge-case behavior (nonexistent deck, name constraints), which is minor for a rename operation.

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

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

Schema description coverage is 100% and both parameters are documented in the schema. The description merely restates the two required names without adding format, constraints, or naming rules. Baseline 3 is appropriate when the schema does 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?

States a specific verb and resource ('Rename an existing deck'), which is unambiguous and clearly differs from deck_create and deck_delete in the sibling list. It does not explicitly name a sibling, but the mutation-on-existing-deck scope is clear enough on its own.

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 guidance on when to use this versus deck_create, deck_delete, or any deck-listing tool, and no prerequisites such as ownership or required permissions. An agent must infer that a deck 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond the annotation layer—no mention of data source (live vs local), caching, rate limiting, or output shape, all of which matter given the 22 generic flags and openWorld hint.

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 that names the three key metrics. It is appropriately sized for the purpose, though it could carry one more clause on output/usage without bloat.

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

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

For a read-only analytics tool with 22 optional generic flags and no output schema, the description names the metrics but doesn't explain data source behavior (live vs local fallback), output format, or how the analysis is scoped. An agent can invoke it with defaults, but understanding the result and source provenance is left to the schema flags.

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 every parameter (csv, json, data-source, max-age, etc.) is self-documented in the schema. The description adds no parameter-specific meaning, so the baseline 3 applies—the schema does 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?

States a specific verb (Analyze) and concrete resources/metrics (review backlog debt ratios, bottleneck decks, clearance days). An agent can tell it produces an analytics summary rather than raw deck or limit data, though it doesn't explicitly name which sibling it replaces (e.g., deck_limits or study).

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, when-not-to-use, or alternative routing. The purpose implies a diagnostic scenario, but nothing tells the agent whether to prefer this over deck_limits, deck_list, or study for examining backlog.

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, readOnlyHint=false and openWorldHint=true, so the safety framing is covered, yet the description adds nothing behavioral — it says 'backup', which reads as a safe copy, without reconciling that against the destructive flag. Critically, it is silent on the traits that actually matter here: `data-source` auto may serve stale local-store data (see `max-age`), `no-cache` bypasses caching, and `dry-run`/`receipt` change side effects.

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

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

One short, front-loaded sentence with no filler — the verb and formats come first and the use cases trail. It is efficiently written, though that efficiency comes at the cost of the detail the task actually requires.

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 26-parameter, destructive-flagged, open-world tool with no output schema and an undefined `resource` domain, a single sentence is far too thin. Nothing tells the agent which resources exist, how confirmation works, or what the output record shape is, leaving major ambiguity for 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?

Schema coverage is 100%, so baseline 3 applies and the schema documents all 26 parameters thoroughly. The description neither adds meaning beyond the schema nor fully aligns with it: it advertises only JSONL/JSON while the schema exposes csv, plain, and quiet output modes.

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 (Export) and names two output formats plus three motivating use cases (backup, migration, analysis). However, the resource is left as the wholly generic word 'data' — nothing says what entities can be exported (cards, decks, notes, search results) — and no sibling is named, so an agent cannot tell when this beats `search`, `sql`, or `card_search` for producing data.

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?

'for backup, migration, or analysis' implies the intent-level context for calling it, which is more than nothing. But there is no explicit when/when-not, no mention of the read-oriented siblings that overlap (search, sql, card_search), and no prerequisites despite a `yes`/`no-input` confirmation flow being part of the schema.

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=false, and openWorldHint=true, so the safety profile is largely covered. The description adds the meaningful detail that this issues create/upsert API calls, but says nothing about partial failure handling, dry-run previewing, or rate-limit pacing — behaviors that matter for a bulk destructive write.

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

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

A single front-loaded sentence with no padding — genuinely tight. It is arguably too sparse for a 25-parameter destructive tool, but it is not verbose or poorly ordered.

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 destructive bulk-import tool with 25 parameters and no output schema, one sentence is markedly incomplete. It omits the existence of dry-run, idempotent no-op handling, allow-partial-failure semantics, and batching, all of which an agent needs to invoke this safely.

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

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

Schema description coverage is 100%, so all 25 parameters are already documented in the schema; the description adds no parameter-level meaning. The baseline of 3 applies, and the description does nothing to compensate for the sheer breadth of options.

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 a specific verb ('Import') and resource ('data from JSONL file') plus the underlying mechanism ('via API create/upsert calls'), so the agent knows what happens. It does not differentiate from the sibling card_import, which overlaps in purpose, leaving ambiguity about which import tool 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 guidance on when to use this versus card_import or any other sibling, and no prerequisites or exclusions are stated. The only hint of usage context ('via API create/upsert') is incidental, not instructional.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that candidates are 'auto-captured' (origin) and pending judgment (state), which is useful context, but says nothing about the default 'open' filter behavior, freshness of local-store data, or result shape.

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

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

A single seven-word sentence with zero waste, and the key qualifier ('awaiting judgment') is front-loaded. Nothing to trim.

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

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

For a read-only list tool with full schema coverage and no output schema, most of what an agent needs is present. The remaining gap is conceptual: it never defines what a 'candidate' is relative to learnings_list entries, which matters for tool selection among five learnings_* siblings.

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% across all 25 parameters, including class, status, limit, and compact, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond what is already documented, making the baseline 3 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?

States a specific verb and resource ('List auto-captured improvement candidates') plus a scope qualifier ('awaiting judgment'), so the agent knows what comes back. However, it does not distinguish itself from the sibling learnings_list, which an agent 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?

The phrase 'awaiting judgment' hints at a review workflow, but the description never says when to call this instead of learnings_list, or that the natural follow-up is learnings_confirm / learnings_reject. No exclusions or prerequisites are given.

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

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

The annotations already establish that this is a non-read-only mutation that is not idempotent. The description adds useful behavior beyond annotations by saying it first prints the full payload and then materializes the candidate, but it does not explain what materialization does, whether it is reversible, or how confirmation behaves.

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

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

The description is a single front-loaded sentence with no filler. It is appropriately brief, though its terseness contributes to gaps better handled in other dimensions.

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

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

For a mutation tool with 23 parameters and no output schema, the description is too thin. It omits what materialization means, how the confirmation flow works, and how this tool relates to sibling learnings commands, leaving the agent to infer too much.

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 schema already documents all 23 parameters, including id, output formats, confirmation, and rate-limit controls. The description adds no parameter-specific meaning beyond the schema, so the baseline score of 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 uses a specific verb ("Confirm") and resource ("open candidate") and adds the two-step behavior of printing the payload before materializing it. It does not differentiate this tool from sibling alternatives such as learnings_reject or learnings_candidates, and "materialize" remains somewhat opaque.

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 implies the tool applies to an open candidate, but gives no explicit guidance on when to choose confirm versus reject or other learnings tools. There are no exclusions, prerequisites, or alternative-routing instructions.

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, readOnlyHint=false, and idempotentHint=false, so the safety profile is carried by structured data. The description's only extra detail, that --all wipes every rule for that query, merely restates the 'all' parameter's schema description, so it adds little beyond structured fields and says nothing about irreversibility or confirmation 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?

A single short sentence with the core action front-loaded and the one modifier appended parenthetically. No filler to cut.

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

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

With 26 parameters and no output schema, the description is thin for a destructive tool: it never mentions that deletion can be narrowed by action or resource, nor that confirmation prompts exist and can be skipped via the 'yes'/'no-input' flags. Annotations and full schema coverage keep this at minimum-viable rather than inadequate.

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 all 26 parameters are already documented and the baseline is 3. The description adds nothing about how query combines with the 'action' and 'resource' narrowing filters or which output/confirmation flags matter for deletion.

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 (delete learnings) plus the matching condition (a query), which is enough to distinguish it from read-only siblings like learnings_list and learnings_stats. It does not, however, clarify how it differs from learnings_reject, the nearest ambiguous sibling.

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 parenthetical explains what --all does, which is implied usage context, but there is no guidance on when to prefer this over learnings_reject, when deletion is inappropriate, or what prerequisites (confirmation, sync state) apply before a destructive call.

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

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

Annotations already disclose readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds the useful detail that it reads from the local ankiweb search_learnings table, but does not explain notable behavioral flags such as warnings mode replacing rows or data-source fallback 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?

The description is a single efficient sentence with the resource and source table front-loaded. There is no filler or redundancy.

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?

Because the schema is fully documented and annotations cover the read-only safety profile, an agent can invoke the tool correctly. However, the description is thin for a 29-parameter tool and does not clarify the relationship to sibling learnings_* tools, which matters for correct selection.

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% across all 29 parameters, so the schema already explains flags like limit, warnings, data-source, and min-confidence. The description adds no parameter-specific semantics beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description gives a clear verb and resource: 'List recorded learnings' from a named table. It does not explicitly distinguish this from sibling tools like learnings_candidates or learnings_stats, so it falls 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?

The description states what the tool does but gives no guidance on when to use it versus alternatives such as learnings_candidates, learnings_stats, or the mutation siblings. An agent must infer the selection criteria from tool names alone.

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. The description adds real value beyond that by disclosing the tombstone effect, implying the rejection is recorded persistently and the derivation won't resurface. It omits, however, that a confirmation prompt is involved (evidenced by the `yes` parameter) and what happens to the underlying candidate record.

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 clause, front-loaded with the action and zero filler. It is efficient, though arguably too sparse for a destructive operation with 23 parameters.

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?

This is an irreversible, destructive mutation inside a learnings loop, with 23 parameters and no output schema. The definition says nothing about reversibility, confirmation behavior, effect on the candidate store, or how it relates to learnings_confirm/candidates, leaving an agent without enough context to invoke it safely.

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

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

Schema description coverage is 100% across 23 parameters, so the schema fully documents flags like `dry-run`, `no-input`, `idempotent` and `receipt`. The description adds nothing about the single required `id` (a candidate identifier) or which flags matter for a destructive one-shot call, so it sits at the schema-covered baseline.

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 ("Reject a candidate") plus a second effect ("tombstone its derivation signature"), which an agent can distinguish from learnings_confirm and learnings_forget by implication. It never names those siblings, and "derivation signature" is domain jargon left unexplained, so the differentiation is inferential rather than explicit.

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

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

There is no when-to-use guidance, no mention of the alternative (learnings_confirm for acceptance), and no statement of prerequisites or irreversibility. With sibling tools learnings_candidates, learnings_confirm and learnings_forget all operating on the same objects, the agent is left to guess which one applies.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the description does not need to restate safety basics. It adds the useful detail that the metrics come from the local events table, but does not explain freshness, aggregation behavior, or sync fallback despite the max-age parameter.

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

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

The description is a single front-loaded sentence with no wasted words. It immediately tells the agent what the tool reports and where the data comes from.

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

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

For a read-only stats tool with full schema coverage and annotations, the description is enough to invoke it, but there is no output schema and the description does not describe the returned metrics or report shape. It also does not clarify how it relates to sibling learnings tools.

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 schema fully documents all 22 optional parameters. The description adds no parameter-level meaning beyond that, which fits the baseline 3 when the schema does the heavy lifting.

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 clear verb, resource, and data source: report learn-loop effectiveness metrics from the local events table. It is more specific than a tautology, but it does not distinguish this stats tool from sibling learnings tools such as learnings_list or learnings_candidates.

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 provides no explicit guidance on when to use this tool versus alternatives like learnings_list, learnings_candidates, or sql. The local events table phrase implies a read-only reporting context, but there are no usage conditions or exclusions.

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

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

Annotations already declare non-read-only, non-destructive, non-idempotent behavior, so the agent knows this mutates state additively. The description adds 'silent', signaling no user-facing output, which is genuinely useful context. However it doesn't say what happens if no playbook exists for the family, or whether the append is visible in later recall/playbook_list calls.

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 with no padding; the action and target come first. The parenthetical 'silent' is slightly cryptic but earns its place as a behavioral cue.

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

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

For a mutation tool with 24 parameters and no output schema, the description covers the core action but omits how the target family is resolved, what happens on missing playbooks, and whether the note affects future recall results. Schema richness compensates for the parameter gap, but behavioral context is thin.

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% across 24 parameters, so the schema itself documents 'query' and 'add-note' fully; the description adds no syntax, format, or constraint detail beyond what the schema provides. Baseline 3 applies when the schema does all the lifting.

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 ('Append a note to an existing playbook'), which clearly distinguishes it from read-only siblings like playbook_list and teach_playbook. The parenthetical adds a mode hint but the core action is 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?

'LLM-fired self-correction' implies the triggering context (agent-driven correction after a recall), which is useful, but it never states when to prefer this over teach_playbook or playbook_list, nor any prerequisite that the family must already exist. The 'existing' qualifier gestures at a precondition without spelling it out.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. However, the description is silent on the notable behaviors implied by the 22 flags — notably data-source (live vs local fallback) and max-age staleness hints — which matter for a cached read. The parenthetical only hints at returned columns.

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 line with zero padding. The parenthetical is slightly cryptic ('content presence'), 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 tool with 22 parameters, no output schema, and a local-vs-live data-source switch, the description is too thin — it does not say where the playbooks come from, whether results can be stale, or what shape the list takes. An agent could call it, but not confidently reason about the result.

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

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

Schema description coverage is 100%, so every parameter is documented in structured data and the baseline of 3 applies. The description's mention of query_family/content presence/last observed loosely maps to select/compact output fields but adds no syntax or semantics 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?

States a specific verb+resource ('List stored playbooks') and names the fields surfaced (query_family, content presence, last observed). It is distinguishable from siblings such as playbook_amend or teach_playbook, though it never explicitly contrasts itself with them.

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

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

No statement of when to use this versus playbook_amend, teach_playbook, recall, or learnings_list, and no preconditions or exclusions. The agent must infer that this is the read-side of the playbook lifecycle from the name alone.

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

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

Annotations already mark this as a safe read-only, open-world, non-destructive operation, so the bar is lower. The description adds the pre-discovery timing context, but it does not disclose behavior around local vs live data, caching, or what 'learnings' actually contain—details that matter for a tool with 26 parameters.

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

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

A single front-loaded sentence with zero waste. It states the action, resource, and timing context immediately.

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 26 parameters, no output schema, and undefined terminology ('learnings'), this description is too sparse. It does not explain what a learning is, what the return shape looks like, or how results differ from learnings_list. The schema covers parameters, but the description leaves major contextual gaps for a complex tool.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema. The description adds no parameter-specific semantics beyond the shared 'query' concept, so baseline 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?

States a specific verb ('Check') and resource ('prior learnings') plus a clear purpose ('before running discovery'). However, it does not distinguish this tool from sibling tools like learnings_list, teach_lookup, or search, leaving ambiguity about which one an agent should choose.

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

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

The phrase 'before running discovery' implies when to use the tool, giving a pre-discovery context. But it names no alternatives, exclusions, or conditions relative to the many sibling learnings and search tools, so usage guidance is only 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=true, destructiveHint=false, openWorldHint=true, and idempotentHint=false, so the safety profile is covered. The description adds two pieces of context annotations cannot express: the sync prerequisite and the relative cost versus pagination. Return shape and result ordering remain undisclosed, which keeps it below a 5.

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

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

Three short sentences, zero filler, with purpose front-loaded and the prerequisite following. Every sentence carries distinct 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 two-parameter read tool with full schema coverage and no output schema, the description supplies the two non-obvious facts an agent needs: search requires a prior sync, and it beats paginating lists. The only shortfall is the unaddressed overlap with sibling search tools.

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%, with the query parameter already documenting FTS5 syntax (AND, OR, NOT, phrases) and limit documenting its default of 25. The description adds nothing beyond 'full-text search', 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 operation: full-text search over all synced data. The resource scope ('all synced data') is clear enough to distinguish it from list/pagination endpoints, but the description never clarifies how it differs from sibling search tools like card_search or shared_search, so an agent cannot be certain which search surface 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?

Offers an implied preference ('Faster than paginating list endpoints') and a prerequisite ('Requires sync first'), which is more than nothing. However, there is no explicit when-not-to-use and no routing against the several sibling search tools (card_search, shared_search, recall, sql), leaving the key selection decision to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds content-level context (the three comparison buckets) but says nothing about data freshness, caching, or the limit param's effect on classification, which would be genuinely useful here.

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 well-formed sentence with the purpose and comparison buckets front-loaded and no filler. It could carry one more sentence of routing or freshness info without bloat, but nothing present 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?

No output schema exists, so the description is the only place to learn what the 'multi-metric digest' actually returns, and it only lists the comparison categories rather than metrics or structure. With 24 mostly generic CLI-style params, the definition is minimally adequate but leaves an agent guessing at result shape.

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 all 24 parameters, including 'topic' and 'limit', are already documented. The description reinforces the topic-centric nature but adds no syntax, format, or default guidance beyond the schema, so the baseline of 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?

Uses a specific verb ('Get') and a well-scoped resource: a multi-metric digest for a topic that compares top-rated, audio-rich, and fresh community decks. An agent can distinguish this from shared_search and shared_info by the 'digest/comparison' framing, 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?

The description implies when it applies (you have a topic and want an overview), but it gives no explicit when-to-use vs when-not guidance and never points to shared_search or shared_info as alternatives for narrower or broader queries.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds '(public)', implying no authentication is needed, which is useful context. However, it does not explain the non-idempotent and openWorld hints, nor the behavior of the no-argument form.

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 telegraphic sentences with the verb and resource front-loaded. Every clause carries some information, though the '(public)' tag is terse enough to be ambiguous.

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, 'Returns the SharedDeck' names the return type but says nothing about its fields. Combined with the unexplained optional-parameter behavior, the description covers the basics but not enough for a fully confident call.

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% for the single deck_id parameter, so the baseline is 3. The description only restates that deck_id is optional, adding nothing about format or the semantics of omitting 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: 'Get detailed information for a community shared deck.' That is clearer than the bare name and tells the agent it retrieves a single deck's detail, though it doesn't explicitly contrast with shared_search or shared_brief.

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 indication of when to choose this over shared_search or shared_brief, and no statement of what happens when deck_id is omitted. The 'Optional: deck_id' note hints at two modes but leaves the agent to guess what the no-argument call returns.

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, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds that results are an array of SharedDeck and that the search is public, but it does not mention pagination, rate limits, or result variability beyond what the annotations imply.

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

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

The description is compact and front-loaded, with no wasted sentences. It covers purpose, parameters, default, return type, and public visibility in a very small space.

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

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

For a simple two-parameter search tool with full schema coverage and clear annotations, the description provides enough context to call it correctly. It names the return type even though there is no output schema, though it omits any detail about SharedDeck fields or pagination behavior.

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 schema already documents both parameters. The description adds useful semantics by stating both parameters are optional and that limit defaults to 50, which is not specified in 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 states a specific verb and resource: 'Search community shared decks on AnkiWeb.' It is clear what the tool does, but it does not explicitly differentiate from related siblings such as shared_brief, shared_info, or the generic search tool.

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 tool's purpose. There is no explicit guidance on when to use shared_search versus sibling tools like search, shared_brief, or shared_info, nor any stated exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is largely covered. The description adds useful context by stating it operates on a local database, covers synced resources, and requires a prior sync. It does not disclose row limits, timeouts, cost, or error behavior for complex queries, which would be helpful for a SQL tool.

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

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

Three short sentences, front-loaded with the core action, then usage scope, then prerequisite. Every sentence earns its place with no redundancy 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?

For a one-parameter SQL tool with no output schema, the description covers the essential prerequisites and scope. However, it does not mention constraints such as query timeout, row limits, or result shape. An agent could invoke it correctly, but would lack guidance on operational boundaries.

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 only one parameter and schema description coverage is 100%, so the schema already carries the burden. The schema's query description is very rich, including table structure and an example using json_extract. The tool description adds no parameter-specific detail beyond the schema, so baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Run read-only SQL against local database.' It also scopes the tool to 'synced resources' and 'ad-hoc analysis, aggregations, and joins,' which helps distinguish it from simpler search tools. However, it does not explicitly name siblings like search or export, so differentiation requires inference.

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

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

It gives clear usage context: 'Use for ad-hoc analysis, aggregations, and joins across synced resources.' It also states the prerequisite 'Requires sync first.' It does not name alternatives or say when not to use SQL, so it falls short of explicit routing 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 destructiveHint=true and openWorldHint=true, so side effects are flagged structurally; the description adds only the interaction model. It omits what grading actually does to card scheduling/state, whether progress is committed per card, and how to run it headlessly even though --agent/--no-input exist in the 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?

One sentence, front-loaded with the verb and resource, no filler. It is efficiently sized but under-specified rather than over-long, and gives no structural hooks for a 24-parameter tool.

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?

Placeholder.

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% across 24 parameters, so the schema does the heavy lifting and baseline 3 applies. The description adds no parameter meaning, and its 'interactive keyboard shortcuts' framing actively pulls against flags like --no-input, --agent, --dry-run.

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

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

States a specific verb pair and resource: 'review and grade due flashcards', plus the modality ('interactively in your terminal with keyboard shortcuts'). An agent can tell it is a study/review session tool, though nothing distinguishes it from siblings like recall or teach.

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 guidance on when to pick this over recall, teach, or deck_triage, and no prerequisites (which deck, due-queue requirements, sync state). The single sentence asserts a terminal-interactive mode that conflicts with the agent-oriented flags in the same tool.

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, openWorldHint=true, and idempotentHint=false, so the agent knows this is a risky, mutable operation. The description adds only the destination store and offline purpose; it does not disclose behaviors like checkpoint-based resume, full-resync pruning, confirmation prompts, rate limiting, or partial-failure handling.

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

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

The single sentence is front-loaded and wastes no words. It is efficiently sized for the core purpose, though its brevity contributes to under-specification elsewhere.

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 complex 33-parameter sync tool with destructive and open-world annotations, one sentence is far too thin. It omits how incremental sync works, what full resync prunes, how resources are scoped, and when to use this versus live-query siblings.

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 all 33 parameters are already documented in the schema. The description adds no parameter-specific guidance beyond what the schema provides, which is the baseline expectation at full coverage.

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 (Sync), source (API data), destination (local SQLite), and intended use (offline search and analysis). It distinguishes the tool from live-query siblings by naming the local-store/offline purpose, though it does not explicitly name alternatives.

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

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

It implies a use case ('offline search and analysis') but gives no explicit when-to-use guidance, no prerequisites, and no comparison to live-search siblings such as search or sql. An agent must infer whether to run sync versus query live data.

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 that this is a non-read-only, non-destructive operation, so the agent knows it performs a write. The description adds useful behavioral context by saying it is LLM-fired and silent, implying background invocation and minimal user-facing output. It does not explain persistence, validation behavior, or side effects beyond what the annotations provide.

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

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

The description is a single tightly written sentence with the core action front-loaded. There is no wasted text, and the parenthetical conveys invocation context efficiently.

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

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

For a tool with 32 parameters, multiple sibling teach/recall tools, and no output schema, the description is extremely thin. It does not explain what gets stored, how validation works, or how it relates to teach_lookup and teach_playbook, leaving substantial contextual gaps despite the rich schema.

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 schema already documents all 32 parameters in detail. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific action and object: recording a query-to-resource mapping for later recall. The parenthetical '(LLM-fired, silent)' further identifies the intended invocation mode. It does not explicitly distinguish itself from sibling tools such as teach_lookup, teach_pattern, or teach_playbook, which keeps it from 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?

The description implies usage through 'for future recall' and '(LLM-fired, silent)', but it gives no explicit guidance on when to use this tool versus teach_lookup, teach_pattern, teach_playbook, or learnings_confirm. An agent must infer the intended situation from the name and sibling names alone.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, and 'Install' is consistent with a write, but the description adds no behavioral context: it doesn't say whether existing rows are overwritten, whether confirmation is required (the 'yes' param hints at prompts), or how this interacts with the teach/recall learning loop (the 'no-learn' param).

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 clause with zero padding — the core action and its key inputs come first. It is arguably over-terse for a 25-parameter mutation tool, but that is a completeness problem rather than a conciseness one.

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 non-idempotent write tool with 25 parameters, no output schema, and a rich surrounding teach/recall ecosystem, one parenthetical is not enough. The agent is left guessing about confirmation, overwrite semantics, and return values.

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 25 parameters are fully documented in structured data and the baseline is 3. The description does usefully highlight kind/canonical/value as the meaningful inputs (the schema's required list is empty even though those descriptions say 'required'), but it adds no syntax or constraint 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?

States a specific verb ('Install') and resource ('manual entity-lookup row') plus the three key fields (kind, canonical, value), so an agent can tell it writes a manual lookup alias rather than a pattern or playbook. It does not explicitly differentiate itself from siblings teach, teach_pattern, and teach_playbook, which would be needed for 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?

There is no statement of when to use this versus teach, teach_pattern, teach_playbook, or recall — the closest siblings. No prerequisites, no exclusions, and no indication of what happens when a kind already exists.

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

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

Annotations declare readOnlyHint=false but not destructive, and the description adds nothing beyond that — no word on what state is created, whether re-teaching overwrites an existing pattern, whether confirmation is prompted, or how failures surface. For a write tool with 28 parameters of shared CLI plumbing, that is a real gap.

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 only weakness is that brevity here is achieved by omission rather than by tight editing of necessary content.

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 28-parameter write tool with no output schema and thin annotations needs far more than one clause: what a pattern consists of, what happens on conflict, and how it interacts with the recall/learn loop are all 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; the description does point at the three semantically important parameters (query-template, resource-template, entity-kind), which helps an agent ignore the ~24 generic output/transport flags. It does not explain the {entity} placeholder syntax or the {entity:country} typed slot beyond what the schema already says.

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 verb 'Install' plus the parenthetical naming of the three core inputs (query_template, resource_template, entity_kind) gives a rough idea of what is written. However, 'manual generalization pattern' is internal jargon that an agent cannot map cleanly onto the sibling tools teach, teach_lookup, and teach_playbook, so the purpose is only partially disambiguated.

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 statement of when to use this instead of teach, teach_lookup, teach_playbook, or learnings_confirm, nor any prerequisite such as registering the entity kind first. The agent must infer the correct tool from the name alone.

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=false, destructiveHint=false, and openWorldHint=false, so the agent knows this is a non-idempotent local write. The description adds nothing beyond repeating the name: it does not say whether the playbook is persisted, deduplicated, validated, or how it interacts with the teach/recall loop implied by the no-learn parameter. Given zero additional context, this is a thin disclosure.

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 well-formed sentence with zero waste, and the write action is front-loaded. It is efficient, though arguably too sparse given the 27-parameter surface.

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 complex write tool with 27 parameters, no output schema, and non-idempotent/non-destructive annotations, the description omits too much: return behavior, persistence, interaction with the learning loop, and whether re-recording overwrites. The schema covers parameters, but the description leaves key behavioral gaps an agent needs.

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 every one of the 27 parameters is already documented in the schema (including mutually exclusive notes/notes-file and playbook-file/playbook-json). The description adds no guidance on usage of these parameters, so it is purely at the baseline level relative to the schema.

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

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

States a specific verb (Record), resources (a CLI playbook + free-text notes), and scope (a query family). An agent can infer the tool writes reusable knowledge rather than reading it. It does not distinguish itself from nearby siblings like teach, teach_pattern, or playbook_amend, so it stops 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?

There is no indication of when to use this versus teach, teach_lookup, teach_pattern, or playbook_amend, nor any prerequisites. The usage context is only inferred from the name and the single sentence. No exclusions or alternatives are named.

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

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

Annotations declare destructiveHint=true and idempotentHint=false, yet the description says only 'sync', which reads as an additive refresh and never warns that local-store data may be replaced (the 'full re-archive' flag reinforces this risk). It also omits that this is a long, network-heavy, open-world operation subject to timeouts and partial failures — all facts an agent needs before invoking it.

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

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

A single front-loaded sentence with zero filler. It is efficient, though the brevity here reflects under-specification rather than disciplined editing.

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 destructive, open-world, 24-parameter mutation of local state with no output schema, one sentence is inadequate. The agent gets no picture of scope ('all resources' — how many?), duration, failure semantics, or what is overwritten.

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 all 24 parameters are already documented in the schema, and the description adds no parameter-level meaning. Baseline 3 applies for a fully documented schema, though the sheer parameter count makes the absence of any highlight (e.g. 'full' vs default incremental) a missed opportunity.

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 verb ('sync') and a destination ('local store') plus a rationale ('offline access and search'), but 'all resources' is vague and it never distinguishes itself from the sibling 'sync' tool or from 'workflow_status'. An agent can guess the general shape of the operation but cannot tell why it should pick this over 'sync'.

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

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

There is no guidance on when to run this versus 'sync', when a full re-archive is warranted, or what prerequisites exist. The offline-access rationale implies a use case, but no exclusions or alternatives are stated.

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