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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description correctly aligns with them while adding non-obvious context: the exclusion of scheduled maintenance visits (which materially changes the result set) and the fact that per-revisit labour and material costs are returned. It stops short of describing result ordering or scale limits.

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 sentences, zero filler. The core behaviour and its exclusions come first, with the parameter detail tucked at the end as supporting 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?

No output schema exists, so the description must convey the return content — it does so at a summary level (cost per revisit). What the record's shape, grouping, or ordering is remains unspecified, but for a single-parameter read-only analytical query this is close to 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 0% and the schema has no default, so the description carries the full burden for the single parameter — and it does: 'days' sets the lookback window in days with a default of 14. Only a stated valid range or unit edge cases are missing.

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 detection target (repeat visits to the same customer for the same trade) and two scoping constraints (within N days, excluding scheduled maintenance), plus the reported output (labour + material cost per revisit). No sibling tool overlaps with 'rework detection', so an agent can pick this without opening the schema.

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?

Usage is implied by the definition — call it to find rework/return-visit cases — but there is no explicit when-to-use guidance, no when-not guidance, and no named alternative (e.g. unbilled_completed_jobs or broken_promises) that might overlap in a rework investigation. Adequate but leaves routing to inference.

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