expiries_list

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 and does a solid job: it explains ordering semantics (expired first), the status vocabulary (ok, due, expired, renewed), the vehicle object shape with null for company-level items, and the meaning of renewedFromId. It stops short of mentioning pagination, authentication, or response envelope, but for a read-only list operation the core behavior is well covered.

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 compact and dense: two sentences that front-load the core purpose and ordering, then pack item shape and filter meanings without repetition or filler. Every clause adds useful information for invoking the tool correctly.

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?

Given that there is no output schema, the description usefully enumerates the item fields (daysLeft, status, vehicle, renewedFromId) and explains each status value and filter. It is slightly incomplete regarding default behavior when no filters are supplied and pagination, but for a list endpoint with no required parameters it gives enough context to make a correct first call.

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 20% (companyId is described in the schema), and the tool description compensates by explaining the semantics of key filters: companyLevel means items without a vehicle, includeClosed means renewed items for history, and vehicleId and kind are listed as filters. It does not expand on kind enum values, but the schema provides them, making the combined coverage strong.

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 identifies this as a listing tool for expiry items, with a specific resource (vehicle documents and company-level items), ordering (soonest first, expired first), and included fields. It does not explicitly name a sibling alternative like expiries_upcoming, but the inclusion of expired and renewed items and the companyLevel filter imply the broader scope, making the purpose reasonably distinguishable.

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 explains available filters but provides no explicit guidance on when to use this tool versus closely related siblings such as expiries_upcoming, expiries_get, or expiries_renew. There is no when/when-not statement or mention of alternative tools, so the agent must infer usage context from the name and filters alone.

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