overdue_listEvery unpaid invoice past its due date: how many days late, what is still owed, which letters have gone out, and what is due next and when. Sorted by days late, worst first.
| Name | Required | Description | Default |
|---|---|---|---|
| on | No | The date to judge lateness against, YYYY-MM-DD. Default today | |
| limit | No | Maximum rows, default and ceiling 2000 |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does meaningful work: it discloses the derived fields returned (days late, amount owed, letters sent, next due date) and the sort order (days late, worst first). Read-only nature is only implied by 'list', and permissions/limits/rate behavior are unaddressed, so not a 5.
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?
A single dense sentence with the scope front-loaded and a trailing clause on ordering; there is no filler. The clause 'what is due next and when' is slightly loose, keeping it just short of a 5.
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 list tool with no output schema and no annotations, the description compensates well by describing the shape and ordering of results. It leaves minor gaps around the as-of date semantics and the 2000-row default/ceiling, but those live in 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?
Schema description coverage is 100%, so both parameters (as-of date and row limit) are already documented in the schema. The description adds nothing parameter-specific — notably it never mentions that lateness is judged against a caller-supplied date — so the baseline 3 applies.
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 gives a specific verb/resource (list unpaid invoices past due date) and enumerates the returned fields, so an agent knows exactly what it produces. It does not, however, distinguish itself from close siblings like aging_summary or chase_today, so a 4 rather than a 5.
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?
There is no explicit when-to-use guidance, no exclusions, and no naming of alternatives such as aging_summary (aggregate view) or chase_today (action on today's chases). Scope is implied by the field list, but the agent gets no routing help for a crowded sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.