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

With no annotations, the description carries the full burden and does so unusually well: it discloses billing rules, SMS 24-month window semantics (window_end), null-vs-zero behavior, the data_quality_flags values, that a carrier inspected only after window_end reads as none, and that crash counts are a ~19% undercount floor. This is rich operational context an agent could not get from the schema.

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?

Front-loads the core purpose and the billing/not_found rule, then breaks detail into two parallel sections (inspections, crashes) which is well-structured. It is long and dense but nearly every sentence carries semantic weight; only the trailing 'Counts, not a rating' framing is slightly redundant with the earlier null-vs-zero discussion.

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 no output schema, no annotations, and a single opaque parameter, the description fills every gap an agent needs: what is returned, what the boundaries and known biases are, what the null semantics mean, and the billing risk. Nothing essential to correct invocation is missing.

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?

Only one parameter (usdot_number) with 0% schema description coverage. The description tells the agent what a USDOT number must resolve to and what happens when it doesn't, which adds real meaning, but it never describes format, bounds, or validation. Adequate but not compensating for the coverage gap.

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 specific verb and resource: returns a carrier's roadside inspection, violation and crash summary, keyed by USDOT. It distinguishes itself from siblings like get_safety_history and lookup_carrier by explicitly framing the output as counts-based SMS/crash data rather than identity or 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?

Explains billing and resolution behavior (paid flat price, billed whenever USDOT resolves, free not_found for unknown numbers), which effectively tells an agent when this tool pays off versus erroring. It does not explicitly name a sibling alternative for inspection/crash data, so it stops short of full when-not guidance.

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