prepare_claims

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.