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

With no annotations at all, the description carries the entire burden and does so unusually well: billing behavior, the fact that null means 'not tracked on that date' rather than a negative answer, the exact date thresholds for each field cohort, the exclusion of first-tracking rows from changelog, and two data-quality traps (the 2026-09-02 licensing-system switch and the 2026-10-10 tier method change) an agent would otherwise misread as carrier behavior.

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?

Purpose and pricing are front-loaded, then the caveats follow in a deliberate order. It is dense and long, but nearly every clause conveys a non-obvious data caveat that would cost the agent a wrong inference; only minor tightening is possible.

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 tool with no annotations and no output schema, the description covers return semantics (field names, null behavior, changelog contents) and data provenance thoroughly. The remaining gap is the since_date contract, which is left undefined in both the description and 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 0%, so the description must compensate for both parameters, but it never explains what since_date filters (snapshots only? changelog only? both?) or its interaction with the history rows. usdot_number is only implied via the word 'carrier'; the schema itself carries no titles or descriptions either.

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 first sentence names a specific resource and output type: 'Historical snapshots and changelog entries for a carrier.' That is concrete enough to separate it from snapshot-only or inspection/crash siblings (get_inspection_crash_summary), but it never names an alternative tool or an explicit boundary, so the differentiation is left implicit.

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?

Nothing states when to reach for this tool versus lookup_carrier, check_roster_changes, or get_inspection_crash_summary. The only conditional guidance is commercial ('you pay only when a call returns records; an exact-key miss is free'), which is a cost incentive, not a use-case rule.

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