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

Despite sparse annotations, the description discloses concrete side effects: it writes '<name>-references.qmd' and '.json' into report_dir (default '_starbuck' next to the manuscript) and renders formats (default html, docx for Word). This matches and enriches the non-readOnly/openWorld annotation profile. It stops short of stating overwrite semantics or whether rendering failures are fatal.

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

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

Front-loaded with the core action and effect, followed by input syntax and then output/return details. Sentences are dense and each carries information, though the second sentence packs two citation dialects together in a way that reads slightly run-on.

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 five-parameter, no-output-schema tool the description covers input dialects, output artifacts and their location, rendering formats, and even the return payload (count plus first 10 uncited-finding sentences). An agent has enough to invoke it correctly without inspecting the 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?

With 0% schema description coverage, the description must carry the load, and it does for four of five parameters: path (implicit), formats (default ["html"], "docx" for Word), report_dir (default '_starbuck next to the manuscript'), and bibliography (from YAML header or supplied here). Only 'include_uncited' is left undocumented, which is the one gap keeping this from a 5.

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

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

States a specific verb+resource pair ('Check every cited reference of a Markdown or Quarto manuscript and write a report') and details the two supported citation syntaxes, so an agent knows exactly what the tool consumes and produces. It does not, however, distinguish itself from the close sibling 'check_references', leaving the agent to guess which 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?

The description implicitly scopes usage by enumerating supported inputs (Markdown/Quarto, [@citekey] with YAML bibliography, or numbered [1] citations with a References heading) and overrides (bibliography 'given here'), which helps the agent decide applicability. But it never states when to use this vs check_references, prepare_claims, or record_claims, and gives 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 establish this as a safe, read-only, open-world operation, so the bar is lower. The description adds a real behavioral nuance — the number of comparison levels depends on whether citation details are supplied — but the 'levels' are never defined, so the agent cannot act on that distinction. No return shape or failure behavior is described.

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

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

Three tight sentences with the accepted-input forms front-loaded and the usage cue last. The unexplained 'level 2'/'levels 1 and 3' phrasing adds words whose meaning is not resolved, but there is no filler.

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

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

For a read-only checking tool with no output schema and no annotations beyond read-only/open-world, the definition covers inputs and usage but omits what a check actually returns (pass/fail? per-level verdicts?) and leaves 'level 1/2/3' undefined. An agent can call it, but cannot anticipate 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?

Reported schema coverage is 0% at the top level, so the description must carry weight, and it does tell the agent that a lone identifier and full citation details are both valid inputs. However, it never explains the relationship between 'raw' and the individual fields, nor how 'identifier' formats (DOI/pmid/arXiv/isbn) are consumed.

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 ('references') and clarifies the accepted inputs (identifier, citation details, or both). It does not name the sibling check_manuscript, though the closing sentence ('sources of a report you wrote') hints at the distinction. The unexplained 'level 1/2/3' jargon keeps it from being fully self-explanatory.

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 a concrete triggering condition ('Use this for the sources of a report you wrote') and specifies which comparison applies under each input mode (citation details vs. identifier alone). It stops short of naming the alternative tool or stating when not to use it.

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

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

Goes beyond annotations by disclosing concrete side effects: it writes <name>-references.json and <name>-claims.json to report_dir (default _starbuck), and that results are paged via offset/limit with a total count. readOnlyHint=false and idempotentHint=true are consistent with this file-writing, paginated read. It does not cover auth requirements or whether existing report files are overwritten.

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

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

Four sentences that are dense with useful workflow, paging, and output-file detail, and the purpose leads. However, 'Level 4, step 1' and 'levels 1 to 3' consume space with pipeline jargon an agent may not be able to resolve, diluting the front-loaded clarity.

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 6-parameter, file-writing, paginated tool with no output schema and 0% schema coverage, the description supplies workflow, return shape, paging, and artifact names — but the required 'path' and 'bibliography' inputs remain unexplained, leaving a gap the agent cannot fill elsewhere.

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

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

Schema description coverage is 0% across 6 parameters, so the description must carry the load — and it only explains texts ({citekey: path}), offset/limit, report_dir, and the default. The required 'path' parameter and 'bibliography' are never described, leaving the most important input and one other undocumented in both places.

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 (check the references at levels 1–3) and a concrete return (best passages for each citing sentence), and names the follow-up sibling record_claims. The 'Level 4, step 1' framing is opaque without pipeline context, but the core verb+resource is discernible and clearly separated from record_claims.

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 sequences the workflow: 'Judge each claim from its passages, then call record_claims', which tells the agent what to do with the output and which tool comes next. It stops short of stating when NOT to use this tool or what alternative exists if the references are not already checked.

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 the safety profile (non-destructive, idempotent, open-world, mutating), and the description adds value beyond them by disclosing a specific business rule: a quote that is not found in the source downgrades the verdict to cannot_assess. It also reveals the side effect of appending verdicts to the report and rendering it, which is consistent with readOnlyHint=false.

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

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

Three dense sentences that front-load position and behavior with little waste. The 'Level 4, step 2' prefix is somewhat opaque but functions as an ordering cue, and every remaining clause (quote check, fallback, render, call guidance) 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?

A mutating, file-writing tool with 5 parameters, no output schema, and zero schema descriptions needs more from the description than it provides, particularly on path/formats/report_dir. The workflow and fallback rule are covered, but the input surface is left largely unexplained.

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

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

With 5 parameters and 0% top-level schema description coverage, the description must explain path, formats, judged_by and report_dir, but it only gestures at 'verdicts' and the source text. The agent is left guessing what path points to (source? report?), what formats does, and the role of judged_by.

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 specific actions (checks each quote against the source, records verdicts, renders the report) on a clear resource (claims), and names the upstream sibling prepare_claims. It is distinguishable from check_manuscript and check_references, though the cryptic 'Level 4, step 2' opener only carries meaning if the agent already knows the pipeline.

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

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

Gives an explicit call directive: 'Give the verdicts of all claims from prepare_claims in one call,' which tells the agent the prerequisite step and that it should be a single batched invocation. It does not explicitly contrast with the other siblings (check_manuscript, check_references), so there is no when-not guidance.

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