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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It covers several important behaviors: CSL-type validation, duplicate-ID checking, creating a .bak backup before writing, and returning the created YAML block. However, it does not specify what happens when a duplicate ID is found or when validation fails, leaving failure semantics unclear.

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 three compact sentences with no filler. The core action is front-loaded in the first sentence, followed by behavioral guarantees and the return value. Every sentence contributes meaningful 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?

The description covers purpose, validation behavior, backup side effect, and return value, which is strong for a tool with no annotations and no output schema. However, it omits failure behavior on duplicate IDs, invalid required fields, and whether the target file must already exist or may be created. These are meaningful gaps for a mutation 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 the schema already documents the file, entry, and style parameters thoroughly. The description adds context about CSL-type validation and duplicate checking, but it does not clarify parameter-specific details like file path resolution or the exact effect of the optional style parameter, which keeps it at the baseline 3.

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 is explicit: 'Add a new bibliography entry' uses a specific verb and resource, and the word 'new' distinguishes this from sibling operations like update, delete, get, and exists. It also states the key behaviors—validation, duplicate checking, backup creation, and return value—so an agent can identify the tool's role immediately.

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 clearly states the intended use: creating a new bibliography entry, not updating or deleting one. It communicates the context of adding entries with validation and duplicate-ID checks, but it does not explicitly mention alternatives like bib:update for existing entries or bib:validate for pre-validation, so no exclusions are stated.

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

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

With no annotations available, the description carries the full behavioral burden. It goes beyond the basic delete semantics by disclosing that a .bak backup is created before the file is written, which is valuable safety-relevant context. It does not, however, describe error behavior for missing IDs or whether the backup guarantees restoration.

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

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

Two short sentences, no filler. The primary action is front-loaded and the backup side effect is presented immediately after, making the most important behavioral trait easy to notice.

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 delete operation with fully described schema properties, the description covers the action and the key side effect. It could additionally mention behavior when the ID does not exist, but nothing essential is missing for invoking the tool 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%, so both id and file are already documented at the schema level. The description's 'by ID' reinforces the id parameter but adds no new detail beyond the schema.

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

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

The description states a specific action ('Remove') on a specific resource ('a bibliography entry') with an explicit key ('by ID'). This clearly separates the tool from siblings like bib:list, bib:search, and bib:update without relying on the tool name alone.

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 intended use is implied: call this when a specific bibliography entry ID needs to be removed. However, the description does not explicitly state when to prefer this over alternatives like bib:update, or mention that the ID should first be discovered via bib:list or bib:search.

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

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

With no annotations provided, the description carries the burden of explaining behavior. It does disclose that this is a boolean check and that it is fast, implying a read-only, lightweight operation. However, it does not describe error behavior, such as what happens if the file is missing or malformed, nor does it clarify how existence is determined.

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 extremely concise: two short sentences with no filler. The core purpose is front-loaded, and the behavioral hint ('Fast boolean check') is placed immediately after, making it easy for an agent to parse quickly.

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 existence-check tool with two required parameters, the description is mostly complete: it states the purpose, the return nature (boolean), and the workflow context. It does not need an output schema because the return type is implied, though it could have mentioned alternatives or error handling to be fully self-sufficient.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the file parameter's meaning and lookup guidance. The description adds only the phrase 'citation ID' to reinforce what the id parameter references, but does not significantly go 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 clearly states the action ('Check if a citation ID exists in the bibliography') and the resource ('the bibliography'), with an added hint about it being a 'Fast boolean check'. This distinguishes it from operations like adding, updating, or deleting, though it does not explicitly name a sibling alternative such as bib:get or bib:search.

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 citing' gives a clear workflow context for when this tool should be used. It does not explicitly discuss when not to use it or name alternatives, but the intended use case is evident and not misleading.

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?

There are no annotations, so the description carries the behavioral burden. 'Retrieve' clearly signals a read-only operation, and 'Returns the full YAML block' tells the agent exactly what output to expect. It does not cover not-found behavior, but for a simple lookup this is reasonably transparent.

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, front-loaded sentences with no filler. The first states the operation, the second states the return value. Every word earns its place.

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

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

For a simple two-parameter lookup, the description plus schema are nearly complete: required parameters are documented, the file parameter includes a concrete discovery strategy, and the return type is specified. The only notable gap is behavior on missing or invalid IDs.

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

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

Schema description coverage is 100%, and the input schema already explains both parameters, including the id example and the file discovery hint. The description adds no new parameter semantics beyond 'by ID,' so the baseline of 3 is appropriate.

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

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

The description states a specific verb ('Retrieve'), a specific resource ('single bibliography entry'), and a precise retrieval method ('by ID'). It also names the return format ('full YAML block'), which distinguishes it from siblings like bib:search and bib:exists.

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 this tool should be used when the agent already has a citation ID and wants the complete entry. However, it does not explicitly contrast this with bib:search or bib:exists, nor does it state what to do when the ID is unknown or when listing entries.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It clearly signals a read-only listing operation filtered by CSL type, which is valuable, but it does not reconcile the claim 'all' with the required limit parameter or disclose pagination/ordering 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, front-loaded sentence that states the action and resource immediately. The examples are placed at the end and there is no filler or redundant phrasing.

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 the lack of annotations, lack of output schema, and the large sibling toolset, the description is incomplete. It does not explain output format, result truncation, or how to choose between bib:list and the many related bib: tools, 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?

The input schema already describes all three parameters, so this is a baseline 3. The description adds only an extra CSL type example ('chapter') and does not add meaningful semantics for file or limit beyond the schema 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 uses a clear verb ('List'), names the resource ('bibliography entries'), and specifies the filtering dimension ('CSL type') with helpful examples. It does not explicitly distinguish itself from siblings like bib:search or bib:get, but the core function 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?

There is no guidance on when to choose bib:list over siblings such as bib:search, bib:get, or bib:stats, and no exclusion criteria. The phrase 'given CSL type' implies a filtering use case, but an agent navigating 13 related tools needs more explicit routing.

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?

There are no annotations, so the description carries the responsibility for behavioral disclosure. It discloses the searched fields and the single-term constraint, but it does not state the result shape, ordering, or whether this is a read-only operation; case-insensitivity is only present in the schema, not the description.

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

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

Two compact sentences front-load the core action and scope before the usage constraint. The example search terms are useful and not filler, making this a tightly written description.

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 three-parameter tool with no output schema, the description plus the highly covered parameter schema is enough to select and invoke the tool correctly. A brief note about what the search returns would be helpful, but it is not required for successful 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 description coverage is 100%, so file, query, and limit are already well documented. The description reinforces the one-query-per-call rule and provides examples, but adds no meaning beyond what the schema already states.

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: 'Search bibliography entries across all fields', and lists the searched fields, which clearly conveys the operation. It does not explicitly contrast with sibling tools like bib:list or bib:get, but 'search' plus the field list makes the scope 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?

It gives an explicit usage rule: one search term per call, with concrete examples and the instruction to make multiple calls for multiple lookups. It does not explain when to prefer this tool over siblings such as bib:get or bib:list, but the term-level guidance is clear.

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

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

With no annotations, the description carries the burden of behavior. It conveys a read-only statistical operation and describes the returned summary, but it does not disclose error behavior, file-required assumptions beyond the schema, or whether it is non-mutating explicitly. For a read-only stats tool this is adequate but not rich.

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

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

One tight sentence that front-loads the action and immediately specifies the output. No filler; every clause earns its place.

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

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

For a single-parameter read-only stats tool, the description plus schema is largely complete: it states what the tool returns and the parameter description tells how to locate the file. The lack of an output schema is partially mitigated by the explicit output summary, but a formal return shape or type names would make it fully complete.

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

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

Schema description coverage is 100% and the file parameter is well documented with an absolute path and lookup guidance, so the description does not need to add parameter details. It adds no extra semantic value but also does not need to.

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') and resource ('bibliography statistics'), and immediately specifies the output composition ('total entry count and breakdown by CSL type'). This clearly differentiates it from sibling tools like bib:list, bib:get, and bib:search, which operate on entries rather than aggregate statistics.

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 makes the use case explicit: an agent needing aggregate counts or a CSL-type breakdown should choose this tool. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough that an agent can distinguish when to use stats rather than list/get/search.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It clearly reveals the mutating nature of the operation, the partial-update semantics, and the side effect of creating a .bak backup before writing. It does not discuss validation failures or return values, but the critical behavioral traits are covered.

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

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

Three short sentences, each with a distinct purpose: state the action, describe partial-update behavior, and flag the backup side effect. There is no filler, repetition, or unnecessary detail.

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 write operation with full schema coverage, the description plus schema provides enough information to call the tool correctly: required file, id, fields, and the behavior of the update. No output schema exists, so return-value details are missing, but that is a minor gap for this kind of mutation 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 the schema already documents id, file, style, and fields. The description reinforces the meaning of the fields parameter by emphasizing that only specified fields change, but it adds little parameter-level detail beyond what the schema already provides.

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 precise operation — 'Update fields of an existing bibliography entry' — with a clear verb, target resource, and scope. The word 'existing' distinguishes it from bib:add, and 'fields of' distinguishes it from bib:delete or bib:get.

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 gives clear context: it is for modifying an existing entry, not creating or deleting one. The sentence 'Only the specified fields are changed; all other fields remain untouched' clarifies that this is a selective update rather than a full replacement. It does not explicitly name sibling alternatives, but the usage context is otherwise clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly communicates that the tool is a read-only validation operation and that it returns a list of errors and warnings. It also specifies the categories of validation performed, giving the agent a good sense of what will happen without requiring a sample call.

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 one tight sentence that leads with the action and resource, then lists the specific checks performed, and ends with the return value. Every clause adds meaningful information, with 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?

For a two-parameter validation tool with no output schema, the description is adequately complete: it names the file, the optional style input's purpose, the categories of validation, and the return shape. It could be even richer by mentioning whether the tool modifies the file or lists usage examples, but it is already sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so both 'file' and 'style' are already well documented in the input schema. The tool description adds only general context about validation, not additional detail about how the parameters are used. This matches the baseline where 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 specific verb ('Validate') and a specific resource ('the entire bibliography file'), and enumerates exactly what is checked: YAML syntax, required fields per CSL type, duplicate IDs, and missing issued dates. This clearly distinguishes bib:validate from sibling tools like bib:list, bib:get, or bib:add, which perform different operations.

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

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

The description makes the tool's purpose clear and implies it should be used to validate a bibliography file, but it does not explicitly state when to prefer it over alternatives or provide exclusions. There is no direct comparison to other sibling tools or guidance on when not to use it, so usage guidance remains implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden. It does disclose the mutating behavior (updating status and optionally note) and the precondition for inputs, which is helpful. However, it does not address what happens when both `ids` and `filter_status` are supplied, whether the operation is atomic, or what response/result the caller should expect.

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

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

The description is two tight sentences with no filler. The primary action is front-loaded, and the selection constraint is stated clearly in the second sentence, making it easy for an agent to parse quickly.

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 bulk mutation tool with no output schema and no annotations, the description covers the core purpose and the input constraint. However, it omits expected return behavior, effect on the registry file, and how combinations of `ids` and `filter_status` are interpreted, leaving some ambiguity for an agent invoking the 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 the schema already documents each parameter. The description adds useful context about the relationship between `ids` and `filter_status` and the requirement that one be provided, but it does not add deeper semantics beyond the schema's property descriptions.

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 clearly identifies the action ('update status and optionally note'), the target ('multiple citations'), and the bulk nature ('at once'). It distinguishes this tool from the single-item sibling ctverify:update by emphasizing batch operation.

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 provides explicit selection criteria: entries can be chosen by a list of IDs or by filtering on current status. It also states the important precondition that at least one of `ids` or `filter_status` must be provided, but it does not explicitly mention when to prefer this tool over the single-update sibling, so it falls just short of full 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?

With no annotations provided, the description carries the full burden and does well: it discloses re-run safety, exact-match preservation, proximity matching behavior (±5 lines), and that ~200 chars of context are captured. It doesn't describe potential failure modes or exact write behavior beyond 'save/merge', but the core behavioral traits are clearly disclosed.

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 dense but well-organized: purpose first, then differentiation, then behavioral guarantees, then workflow. Every sentence contributes meaningful context, and the workflow line provides a compact mental model for the agent.

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 3-parameter tool with no output schema and no annotations, the description covers purpose, usage workflow, registry behavior, and re-run semantics thoroughly. The main gap is that it doesn't describe the exact return value/output format of the extraction, though the purpose strongly implies what the result will contain.

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

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

Schema description coverage is 100%, so the baseline applies. The description does add useful nuance for registry_path (merge/preserve behavior) and dry_run (re-running after edits), but it doesn't add significant meaning beyond the schema's own parameter descriptions.

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?

Description states a specific verb ('Extract'), resource ('citations from Pandoc inline footnotes'), and intent ('verification tracking'). It also explicitly distinguishes itself from bibliography management, which separates it from the sibling bib:* tools. This makes the tool's role 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?

Provides clear workflow context ('extract → set claims → verify each claim → update status') and explicitly notes this is not bibliography management, signaling when not to use it. However, it doesn't name specific sibling tools like ctverify:status or bib:search as alternatives, so the routing is slightly less explicit than it could be.

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

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

With no annotations present, the description carries the full burden of disclosure. It clearly indicates this is a retrieval operation and specifies the returned fields (cite, context, claim, status, note), which is meaningful behavioral context for a read-only getter.

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 entire description is a single, front-loaded sentence with no filler. It communicates the operation, the input style, and the output fields efficiently.

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

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

For a simple two-parameter getter with no output schema, the description covers the essential details: what it retrieves, how it is identified, and what the response includes. It does not discuss error behavior for missing IDs, but that is a minor omission for this tool's low complexity.

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

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

Schema coverage is 100%, so both ids and registry_path are already documented in the input schema. The description adds only the general notion of retrieving 'by ID', which does not materially expand on the schema's existing parameter documentation.

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

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

States a specific action ('Retrieve'), the target resource ('citation entries'), and the lookup mechanism ('by ID'), while also naming the returned fields. This clearly distinguishes it from siblings like ctverify:extract or bib:search.

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 that this tool is for retrieving known citation IDs, but it does not explicitly state when to use it versus alternatives, nor does it mention when not to use it. The guidance is indirect rather than explicit.

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?

No annotations are provided, so the description carries the behavioral disclosure burden. It does disclose that the tool returns counts by status and a citation list, plus filter behavior, which is useful. However, it does not explicitly state that this is a read-only operation, describe the list format/order, or mention any 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?

The description is two tight sentences with no filler. The main purpose is front-loaded, and the follow-up sentence gives practical filter usage. Every phrase earns its place.

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

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

For a tool with 7 parameters, no annotations, and no output schema, the description covers the high-level output and two key filter parameters but leaves gaps: no tool-selection context, no return field details, and no mention of pagination behavior beyond what the schema already states. It is adequate but not comprehensive.

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 adds meaningful semantics beyond the schema by explaining filter_status and filter_claim, particularly clarifying that filter_claim can 'find missing ones' via empty-string matching. This is valuable interpretive context.

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 clearly states the verb and resource: 'Show verification progress of a citation registry' and summarizes the returned content as counts by status and a list of citations. It does not explicitly differentiate from sibling tools like ctverify:get or bib:list, 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?

The description gives filter-level guidance ('Use filter_status... Use filter_claim...') but no guidance on when to choose this tool over siblings such as ctverify:get or bib:list. There is no when-not-to-use or alternative tool mention, so tool-selection guidance is essentially absent.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly conveys mutation, independent field updating, status progression, and upsert-like creation for missing IDs. It leaves some edge behavior unspecified, such as what happens when an ID is missing without a cite or whether the batch is atomic, but it is substantially transparent.

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

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

The description is front-loaded with the core purpose and each subsequent sentence adds distinct value: per-entry independence, claim semantics, status lifecycle, and the upsert condition. There is no filler or unnecessary repetition of schema 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 mutating tool with no annotations and no output schema, the description covers the main invocation-relevant details: what each meaningful field does, how verification status progresses, and when a new entry is created. It does not specify behavior for entries whose IDs are missing and that lack a cite, nor batch atomicity, but these are not strictly necessary for calling the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents parameter types and requirements. The description adds meaningful semantic value by explaining what claim records, how status progresses through the verification states, and when the cite parameter enables new-entry creation. This goes beyond the field descriptions 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 clearly states a specific action and resource: batch update citation verification entries. It also explains the per-entry update capability and conditional creation of new entries. However, it does not explicitly differentiate itself from the sibling tool ctverify:bulk-update, which sounds similarly batch-oriented.

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 about when to use this tool versus alternatives such as ctverify:bulk-update, ctverify:get, or bib:update. The description gives an internal conditional (new entry creation when an ID does not exist and cite is provided), but this is not tool-selection guidance.

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