FMCSA Carrier Intelligence

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

There are no annotations, so the description carries the full burden. It does disclose two genuinely useful traits: the call is paid, and it returns a single flat row rather than a graph. However, it omits auth/permission requirements, rate or cost specifics, and what the returned counts mean or how to interpret a high/low value, so behavioral coverage is only partial.

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?

Two short blocks: the core measurement is front-loaded, and the cost/output note is separated and terse. The nested parenthetical is slightly heavy but every sentence is informative, with no filler.

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?

With no annotations and no output schema, the description must cover invocation and result interpretation. It does identify the source records and the mailing-address exclusion, and signals a single-row result, but leaves the sole parameter undescribed and does not explain what the counts imply for consistency judgments.

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% and there is a single required parameter, usdot_number, which the description never mentions. The schema supplies only type (integer) and required status, so the description should clarify what identifier is expected (USDOT number format) but adds nothing.

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 states a specific resource and measurement: a count of distinct business addresses and phones a carrier reports across named FMCSA record sets (census, licensing/insurance, crash records). It also distinguishes itself from sibling identity tools by noting it is cheaper and returns 'one row, no graph,' which tells an agent this is a lightweight consistency count rather than a full identity resolution.

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?

'Paid. Cheaper than either identity tool; one row, no graph' hints at when to prefer this over check_carrier_identity or screen_carrier_identity, but the guidance is comparative and cost-focused rather than a clear when-to-use statement. There is no explicit trigger condition (e.g. 'use this to spot data conflicts before paying for full identity resolution') and no stated exclusions.

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

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

With no annotations, the description carries the full burden and delivers: exact validation constraints (usdot must not appear in roster, non-empty, max 100 distinct entries), the failure classes and their cost (free invalid_arguments, free not_found), the metered pricing formula, and the reassurance that 'not linked' is a complete billable answer. This is unusually thorough behavioral disclosure.

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 return shape are front-loaded well, and every sentence carries substance. It is somewhat long and repeats the 'still your own input, not a new disclosure' reassurance and cross-references to sibling conventions multiple times, which is slightly redundant though defensible for a metered tool.

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 2-parameter tool with no output schema and no annotations, the description covers inputs, return fields, error/edge cases, cost model, and success semantics — nothing an agent needs to call it correctly 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?

Schema coverage is 0% and both parameters are bare integers, so the description must compensate — and it does: usdot_number is 'the applicant', roster_usdot_numbers is 'your own list, supplied by you', plus the constraint that the applicant must not appear in the roster and the roster's size cap. This adds real meaning the schema cannot convey.

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 ('Screens one applicant carrier against a roster of carriers') and explicitly positions itself as 'the batch generalization of confirm_identity_link', so an agent can distinguish it from siblings without opening any schema.

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 a concrete use case — catching a carrier previously cut from the network re-entering under a new USDOT number — and names the sibling it generalizes (confirm_identity_link). It stops short of an explicit 'when not to use this / use X instead for single pairs' rule, so the routing is implied rather than fully spelled out.

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

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 well: it discloses the billing model, the exact error/not_found conditions, and the data-completeness caveats (legacy archive frozen 2026-05-14, status_source legacy_li, unlisted MOTUS changes, no independent broker count). It also explicitly frames output as a record, not a rating or recommendation.

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-loaded with the core question, then structured into input rules, return fields, and a trust caveat. It is dense and long, but each block (billing, returns, reliability) carries information an agent needs, with only minor verbosity.

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?

With no output schema, the description enumerates the returned fields in detail (authority flag, docket status/continuity, bond BMC-84/85 coverage metrics, event history, revocation/suspension flags, identity linkage) and adds reliability caveats. Nothing needed to interpret or trust the result 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?

Schema coverage is 0% and the two parameters are mutually exclusive optional fields, so the description must compensate. It does: it specifies the accepted MC formats (MC123456, MC-123456, 123456), requires exactly one identifier, and defines the free not_found/error outcomes, though the usdot_number format is left implicit.

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: it answers whether a broker holds active broker authority and reports what FMCSA's record says around it. This is clearly distinguishable from sibling identity/safety tools (check_carrier_identity, get_safety_history) by its broker-authority focus.

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 clear input rules (exactly one of mc_number or usdot_number) and cost semantics (paid and always billed on a resolved carrier; free not_found; free error), which tells the agent when a call is worthwhile. It does not, however, name sibling alternatives or explicitly say when to prefer another tool over this one.

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

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

No annotations exist, so the description carries the full burden and does so unusually well: it discloses billing behavior per outcome, the fact that flagged is FMCSA's ARCHI rule and not a fraud determination, that flagged != match_score >= 1.5, and that score_provenance.match_score_ceiling is computed per carrier and usually caps at 2.5. It also enumerates what the tool deliberately never returns (linked USDOT, legal name, hashes), which prevents an agent from misrepresenting output.

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 purpose and the cheaper alternative are well front-loaded, but the second and third paragraphs are long defensive digressions (why a linked carrier's identity is not the caller's to receive, confirmation from reading Truckin's hashing code) that do not help an agent select or invoke the tool. Substantive content, but several sentences do not earn their place for the invocation decision.

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?

With no output schema, no annotations, and a subtle domain (match scoring, flags, ceilings), the description supplies the interpretive context an agent needs: what flagged means, how it differs from the score threshold, why ceilings vary per carrier, and how billing and not_found behave. Nothing essential to calling or interpreting this tool 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?

There is a single integer parameter with 0% schema description coverage, so the description must compensate. It adds behavioral meaning about the parameter's value (an unknown USDOT number yields a free not_found) but never states the expected format, validity range, or what a USDOT number actually is, leaving the semantic gap only partly filled.

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 (full identity-linkage detail for a carrier) and immediately distinguishes itself from the sibling screen_carrier_identity by purpose and price. An agent can tell exactly which of the two identity tools to pick without opening a schema.

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?

Explicitly routes the agent: 'Priced meaningfully above the free screen_carrier_identity — call that first if you only need the flag and a count.' It also gives exclusions and edge-case outcomes (a carrier with no linked carriers is a valid, billable answer; an unknown USDOT is a free not_found), which is exactly the when/when-not guidance expected.

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

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.

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 richly: privacy guarantees (never discloses identity the caller didn't already have), result semantics (cluster_id returned only when linked), error behavior (invalid_arguments when the two numbers are equal, free; free not_found on unresolved numbers), and pricing behavior (paid, pricier, billed the same for 'not linked').

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-loaded with the core purpose and the key differentiator, then layers in semantics, routing, and pricing. Every sentence carries real information, though the parenthetical cross-references make it longer than strictly necessary.

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?

With no output schema and no annotations, the description fully covers what an agent needs: return semantics (cluster_id only when linked), error cases and cost, and the alternative tool. Nothing required to invoke it correctly 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?

Schema coverage is 0%, so the description must compensate, and it does: it explains that both usdot_number_a and usdot_number_b are caller-supplied, must differ, and must resolve in carrier_identity_cluster. It does not document the value format, but the behavioral constraints it adds go well beyond the bare titles.

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: it confirms or denies that two specified carriers share an identity cluster. It explicitly distinguishes itself from check_carrier_identity and screen_carrier_identity, so an agent can select it without opening any schema.

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?

Explicit when-to-use: when you ALREADY SUSPECT two carriers are linked, as the lower-risk alternative to the removed linked_carriers field. It names the alternative (check_carrier_identity) and the condition that selects it ('who is linked to this carrier?'), giving clear routing.

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

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

With no annotations, the description carries the full burden and largely meets it: it declares the operation is free/never billed, states exactly what is returned (identifiers and a status, no names or addresses), and maps error conditions (unknown docket -> not_found, unreadable -> invalid_arguments). It omits auth requirements and rate limits, so it stops short of 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?

Front-loaded with the outcome ('Free. Finds the USDOT number...') and every subsequent sentence carries concrete information about formats, return fields, or errors. It is dense and longer than typical, but little of it is waste.

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 one-parameter tool with no output schema, the description covers input formats, output semantics (authority_holder_usdot_number, usdot_numbers with holder-first ordering and the two-carrier census case, docket_status/status_source provenance), error behavior, and billing — nothing an agent needs to invoke it correctly 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?

Schema coverage is 0% and the single parameter is undocumented in the schema, so the description must compensate — and it does thoroughly. It enumerates accepted formats ('MC123456', 'MC-123456', 'mc 123456', '123456'), states the bare-number default (taken as MC), and explains zero-padding is ignored because FMCSA files disagree.

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+resource+transformation: it finds the USDOT number for an operating-authority docket number (MC, MX or FF). The scope sentence ('so a broker holding the MC number ... can reach the other tools, which take a USDOT number') distinguishes it from siblings like lookup_carrier or search_carriers that consume a USDOT number directly.

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?

Clearly sets the situation for use: an agent has an MC/docket number and needs a USDOT number to call other tools. That routing context is explicit, though no sibling is named as a direct alternative and no 'do not use when' case is stated.

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

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

With no annotations, the description carries the full burden and delivers: it discloses paid flat pricing, that registry_unavailable calls are not billed, that unknown USDOT numbers return a free not_found, the hashing/verification protocol (record_hash is SHA-256, verify_url confirms issuance), and what is deliberately excluded (safety_tier_derived). This is unusually rich behavioral disclosure for a tool with zero annotation coverage.

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 lead sentence front-loads what the tool is and its price, and the sentences are dense with distinct information. It is long, but almost every clause conveys contents, integrity, or billing facts rather than restating fields; the enumeration is verbose but mostly earns its place.

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 single-parameter, no-output-schema tool, the description is complete: it catalogs the returned sections (profile, SMS, crash summary, changes, identity triage, insurance continuity, authority events, review_factors), explains integrity verification, and states billing edge cases. An agent has everything needed to call and interpret it.

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?

There is one parameter with 0% schema description coverage. The description implies usdot_number identifies the carrier and that an unknown value yields a free not_found, but it never states the expected format (e.g., the bare integer form versus a USDOT prefix), so it only partially compensates for the empty schema.

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 opening sentence states a specific verb+resource: a dated, hashed record of a carrier's public FMCSA data built for a broker's vetting file. It explicitly distinguishes itself from scoring tools ('It is a record, not a score') and enumerates the exact contents, so an agent can separate it from siblings like get_safety_history or check_carrier_identity.

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 context 'built for a broker's carrier-vetting file' implies the use case, and 'Paid, flat price' warns about cost. However, it never states when to choose this comprehensive record over narrower siblings such as get_safety_history, get_inspection_crash_summary, or lookup_carrier, nor any exclusion conditions.

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

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

With no annotations, the description carries the full burden and does well: it discloses that the call is free and unauthenticated (no credentials or paid tier required), which is the key behavioral fact for an agent deciding whether it can call it. It omits rate limits and the response shape details, but the safety profile for a discovery call is effectively 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?

Three short, front-loaded lines: identity, payload, and the imperative call-to-action. No filler, and the most decision-relevant facts (free, unauthenticated) come first.

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?

There is no output schema, so the description must convey the return contents, and it does: tables, fields, pricing, freshness. Combined with the zero-parameter schema, an agent has everything needed to call it correctly; only per-field response detail is left unspecified.

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?

The tool takes zero parameters, so the baseline is 4 and there are no parameter semantics the description could or should add.

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 states a concrete verb+resource ('Free, unauthenticated dataset catalog') and enumerates exactly what it returns: every table sold, its fields, current pricing, and freshness. It does not explicitly contrast with siblings, but the siblings (carrier/identity lookups) are unrelated domains, so no disambiguation trap exists.

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?

'Read this before paying for anything' gives an explicit triggering condition and makes the tool the correct first step of a purchase flow. It stops short of naming alternatives or stating when not to call it, but the guidance is directly actionable.

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

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

With no annotations, the description carries the behavioral burden and does so for the key traits: it is 'free' and 'unauthenticated,' and returns sample rather than live data. It does not mention rate limits, pagination, or error behavior, but for a zero-param read-only sample tool the cost/auth/no-write disclosure is the substantive part.

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?

Two tight sentences, front-loaded with the free/sample framing. Slight redundancy in restating the check_carrier_identity purchase rationale already implied by naming the sibling, but no meaningful waste.

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 simple no-param sample tool with no annotations and no output schema, the description covers cost, auth, and which response shapes are demonstrated. It could be more complete by listing the fields present in the sample, but the essentials an agent needs to call it are present.

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?

Zero parameters, so the schema is trivial and fully self-documenting (100% coverage). There is nothing for the description to add on parameters, making the baseline of 4 appropriate.

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+resource (get identity sample) and explicitly frames it against two named siblings: it covers both screen_carrier_identity's free IdentityScreen shape and check_carrier_identity's paid IdentityAssessment shape. An agent can tell what this returns and how it relates to the identity-checking siblings without opening any schema.

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 a clear usage context and the deciding condition: use it to see the paid response shape and evaluate data quality 'before spending USDC on check_carrier_identity.' It names the relevant alternatives, though it doesn't explicitly say when NOT to use it (e.g., vs. the generic get_sample sibling).

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

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.

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.

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

With no annotations, the description carries the full burden. It usefully discloses two key traits, that the call is free and unauthenticated, but says nothing about sample size, rate limits, or the shape/content of the returned rows, so the behavioral picture is only half drawn.

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?

Two short sentences with zero filler; the core trait (free, unauthenticated sample) is front-loaded and the rationale follows immediately.

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 zero-parameter tool with no output schema, the description covers cost and auth but leaves the returned content unspecified beyond 'carrier_profile rows', and does not resolve the overlap with get_identity_sample. Adequate, but missing context an agent would benefit from before calling.

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?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing about parameters for the description to clarify or omit.

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 names a specific verb and resource ('sample of carrier_profile rows'), which is far more concrete than a tautology like 'gets a sample'. However, it does not distinguish itself from the near-twin sibling get_identity_sample, so an agent cannot tell from the description alone why both exist or how they differ.

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?

It clearly states the context of use: evaluate data quality before spending USDC on the paid tools. This effectively signals when to reach for this tool over the paid ones, though it never names a specific paid sibling or states a when-not condition.

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

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: it discloses the paid model and that exact-key misses are free, warns that all carrier_status values are returned and must be checked, explains the insurance_cancel_pending snapshot semantics and that days_to_cancel_effective counts from record_as_of, and flags the removed contact fields. This is unusually rich operational context.

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 purpose is front-loaded and nearly every sentence carries signal, but the removal history ('removed 2026-09-19, see schemas.CarrierProfile') and repeated insurance caveats add length. Dense and justified overall, with minor trimming 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 six-parameter tool with no annotations and no output schema, the description covers payment, status semantics, cancel-field behavior, and per-claim return values. It relies on a schema reference for the full profile shape rather than enumerating the return payload, leaving a small gap.

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, and it does: claimed_name is matched against legal_name OR dba_name, the address fields match physical_address and any subset may be supplied, and it explains the name_match/physical_address_match booleans and the null-for-unsupplied rule. This fully documents the ambiguous parameters.

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 opening sentence states a specific verb (look up), a singular resource (a carrier's current profile), and the exact key (USDOT number), which cleanly separates it from the plural sibling search_carriers. An agent can identify the tool's job without reading the schema.

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?

It gives strong context for the claimed_* fields (identity confirmation / catching double-brokering) but never states when to choose this tool over siblings like check_carrier_identity or screen_carrier_identity. Usage is implied rather than explicitly routed, so it lands at minimum-viable-plus.

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

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 generously: it discloses that the tool never bills or requires payment, that it deliberately withholds member-identifying fields (USDOT, legal name, link type, hash), that unknown USDOT numbers produce a not_found error, and it flags the ~6% artifact rate in confidence_caveat plus the per-carrier nature of match_score_practical_ceiling.

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 core purpose and the paid-triage routing are front-loaded well, but the middle paragraph is meta-rationale about the 'discovery/sales motion in an agent-only channel' and repeats that it never bills and never requires payment. That rationale is padding an agent does not need to invoke the tool, diluting an otherwise efficient definition.

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?

There is no output schema and no annotations, yet the description qualitatively covers the return surface (flagged boolean, cluster size, linked-carrier count, confidence_caveat, practical match ceiling) and the failure mode, which is what an agent needs before calling. Only the exact response shape and field naming remain unstated, which is a minor gap for a one-parameter screen.

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% for the single usdot_number parameter, and the description adds only indirect semantics: that the value is a USDOT number and that an unknown one yields not_found. It conveys the error behavior but no format, validity, or source guidance for the identifier.

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 states a specific verb+resource ('free triage screen for a carrier') and enumerates exactly what it returns: FMCSA chameleon-carrier flag, identity cluster size, and count of linked carriers with a motive. It explicitly positions itself against the sibling check_carrier_identity (paid, member detail), so an agent can route without opening either schema.

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?

It clearly frames itself as the free first-step triage and names the alternative ('Call check_carrier_identity (paid) for that'), giving an explicit condition that selects the paid sibling. It stops short of stating when this screen is unnecessary or inappropriate (e.g., carriers already known to be clean), so it is clear context without full exclusions.

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

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

With no annotations, the description carries the full behavioral burden and does so well: paid-only-on-returned-rows with zero-row calls free, a hard 100-row cap that overrides the requested limit, Active-only default overridden by include_inactive, and an explicit disclosure that contact fields were removed and why. This is exactly the context annotations would otherwise have to supply.

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?

Information-dense and front-loaded with the payment rule, then tier semantics, then defaults/caps, then the missing-contact-fields caveat. The rhetorical aside about 'the sharpest version of that risk in this product' is editorial padding that costs a point.

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 and no annotations, so the description is the sole source of behavior — and it covers pricing, row caps, default filtering, and the removed-fields risk. The gaps are the unexplained filter parameters (state, cargo_type, authority_status) and any description of the returned record shape beyond what is excluded.

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 six parameters. It explains safety_tier (1–6 scale, derived value, no-tier non-match), include_inactive, and the limit cap, but state, cargo_type, and authority_status are left completely undefined in both schema and description — half the surface remains undocumented.

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+resource ('Filtered carrier search') and immediately frames it as a 'filterable, multi-result endpoint' that returns no contact details, contrasting with lookup_carrier's claimed-identity lookups. An agent can distinguish it from lookup_carrier and find_carrier_by_mc without opening any schema.

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?

Names the alternative (lookup_carrier's claimed_name/claimed_street) and the condition that selects it ('if you need to confirm a specific carrier's claimed identity'), and explains the safety_tier matching rule including the 'never matches' no-tier case. It does not state when to prefer the other sibling search tools (find_carrier_by_mc, get_safety_history), so explicit when-not guidance is incomplete.

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