declarations_recalculate

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. The description does state that it 're-populates data from current invoices,' which implies it modifies the declaration, but it doesn't disclose whether the operation is reversible, what happens to existing data before repopulation, whether it fails on non-draft declarations or silently no-ops, or what the response contains. For a mutation tool with zero annotation coverage, the behavioral transparency is insufficient.

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 concise sentences with zero wasted words. It front-loads the action, states the resource, and adds the critical status constraint. Every sentence 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 mutation tool with no annotations and no output schema, the description should disclose more behavioral detail. The core operation is clear (recalculate a draft from current invoices) and the draft-status constraint is stated, but the description omits what happens on invalid status, whether the recalculation is destructive to custom edits, and what the response indicates. However, the schema fully covers both parameters, so the description is adequate but not complete for a state-changing 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%, so the schema already documents both parameters ('Declaration UUID to recalculate' and 'Company UUID (overrides STORNO_COMPANY_ID env var)'). The description adds the drafting context but doesn't add parameter-level meaning beyond the schema. Notably, the companyId parameter mentions an env var override but no description text explains this anomaly. 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 clearly states the verb (Recalculate), the specific resource (a draft declaration), and the behavior (re-populating data from current invoices). It also distinguishes this tool from siblings by specifying the 'draft' status requirement, setting it apart from declarations_validate, declarations_submit, declarations_sync, and other declaration 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?

The description explicitly states the tool only works on declarations in 'draft' status, which is a clear usage constraint. It doesn't name specific alternatives, but the 'draft' precondition effectively tells the agent when NOT to use this tool. The sibling set includes many declaration-related tools (validate, submit, sync, prepare) but no explicit when-not guidance is given, leaving some ambiguity for the agent.

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