propose_tracker_update

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

No annotations are provided, so the description carries the full burden. It does disclose the most important behavioral trait — that the CSV is not modified — and the append-only data model constraint. However, it does not disclose what happens on validation failure, whether any side effects occur at all, or what the tool returns, which are material for a validation 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?

The description is a single efficient sentence with the critical non-mutation fact front-loaded. Every word earns its place, though 'validate' and 'dry-run' slightly overlap in meaning.

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 9-parameter validation tool with no output schema and no annotations, the description is too thin. An agent calling this correctly needs to know expected formats (timestamps, dates), what validation failure looks like, the shape of the returned proposal, and whether anything else is persisted. Only the no-CSV-change guarantee is covered.

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 only 11%, and the tool description adds nothing about the 9 required parameters. Only clearon_status has in-schema definitions; the other 8 parameters (checked_at_et, item_date, source_url, etc.) have bare types with no format, syntax, or example guidance. With coverage this low, the description was obligated to compensate and does not.

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 dry-run'), a specific resource ('append-only tracker update'), and the key constraint ('without changing the CSV'). It is clearly distinguishable from the sibling apply_tracker_update, which would be the tool that actually writes the change.

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 dry-run framing implies this tool is the pre-flight check before apply_tracker_update, but the description never states that explicitly, never names the alternative, and gives no when-to-use vs when-not-to-use guidance. Usage is only implied by the 'dry-run' wording.

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