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

With no annotations, the description carries the full burden and delivers: paid/metered pricing model, free invalid_arguments on roster overflow (no silent truncation), billing for not-found and no-change results, free not_found when nothing resolves, weekly-but-uncommitted freshness with provenance.record_as_of, filtering of synthetic 'field started being tracked' rows, and a settings-driven row cap surfaced via the 'truncated' flag.

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?

Dense and front-loaded, opening with the core question the tool answers before moving into pricing, limits, and freshness. Every sentence carries information, though the multi-clause prose runs long and could be broken into scannable sections.

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, yet the description adequately characterizes the return: old/new field values, roster_not_found entries, and a 'truncated' flag. Combined with the freshness, billing, and error semantics, an agent has everything needed to call and interpret it correctly.

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 coverage is 0%, so the description must compensate, and it largely does: 'since' is specified as ISO YYYY-MM-DD and roster_usdot_numbers is defined as the caller's own USDOT list with a non-empty constraint and a max distinct-entry limit (currently 100). It could be slightly tighter on the overflow behavior, but both parameters are meaningfully documented.

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 verb+resource+scope: which roster carriers changed on or after a date, and enumerates the tracked fields (authority, insurance, out-of-service) with old/new values. It also distinguishes itself from siblings by noting it carries no contact information and no legal_name/dba_name/phone/email changes, 'same as get_safety_history'.

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?

Gives strong context: it routes pricing questions to get_catalog and aligns its exclusions with get_safety_history. It explains what a 'nothing changed' and 'no entry resolves' result means. It stops short of explicit when-to-use-vs-alternative framing, but the surrounding guidance is clear.

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