Bridges — FHWA National Bridge Inventory: Condition, Posting & Clearance

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

With no annotations, the description carries the behavioral burden and does well: it discloses nearest-first ordering, default and maximum radius, returned distance_km values, and exclusion of bridges without coordinates. It does not explain the limit parameter or pagination behavior, which keeps it below a top score.

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 front-loaded and compact, with each sentence adding useful operational detail about scope, parameters, return values, and exclusions. There is 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?

For a retrieval tool with no output schema and no annotations, the description provides enough to call it correctly: coordinates, radius limits, ordering, and a key returned field. The missing explanation of limit behavior is a minor 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?

The schema already documents lat, lon, and radius_km well, and the description reinforces decimal degrees and the radius default/max. The limit parameter remains unexplained, but coverage is otherwise 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 states a specific operation and resource: finding bridges near a point, with nearest-first ordering. It also distinguishes the spatial scope from the state-scoped sibling tools, so an agent can select it without inspecting 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 clearly explains that this tool takes a point rather than a state, which differentiates it from the state-scoped tools. It does not explicitly compare against all sibling search tools, but the spatial-use condition 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 does real work: it discloses that sentinel 'no restriction' values are excluded, which clearance is used by default (NBI Item 10 vs 54B), and the mutual exclusivity of the height params. It is silent on pagination (the `limit` default of 100), on the read-only nature, and on what the results look like, leaving meaningful gaps for a no-annotation tool.

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 dense sentences ordered purpose-first, then parameter guidance, then an important exclusion caveat. The NBI item references are jargon but they earn their place by disambiguating the `under` flag; nothing is redundant.

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 filtered search with five params and no output schema, the decision-relevant semantics (units, mutual exclusivity, under vs over, sentinel exclusion) are all covered. The missing pieces are the `limit`/result-cap behavior and return shape, which are minor for a 'find' tool but not trivial.

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 60%, and the description compensates well: it explains that max_height_m and max_height_ft are alternatives ('pass one, not both') and that `under` selects between roadway clearance and under-bridge clearance. Only `limit` is left unaddressed by both schema and description.

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+filter: bridges in a state with vertical clearance at or below a threshold. The clearance filter is distinctive enough to separate it from siblings like list_posted_or_closed_bridges or search_bridges, though no sibling is named explicitly.

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 operational context: 'pass one, not both' for the metric/imperial thresholds, and 'set under=true ... which is what matters for routes passing beneath' tells the agent which variant to pick for its use case. No explicit when-not-to-use or alternative-tool routing, which keeps it at 4.

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 are supplied, so the description carries the load. It does disclose the return shape ('full decoded record') and the uniqueness semantics, but it says nothing about what happens when the id is not found, when state is omitted and matches collide, or whether the call is read-only (implied but not stated).

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 sentences, front-loaded with the identity and lookup key, then the disambiguation rule, then the return value. No filler and nothing redundant.

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 two-parameter read lookup with no output schema, this is nearly sufficient: it names the key, the disambiguator, and the return payload. Only failure/ambiguity behavior is left implicit.

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 100%, so the baseline is 3, but the description adds genuine meaning: id is an FHWA Item 8 structure number and state disambiguates because uniqueness is per-state. That rationale is not present in the schema text.

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?

Specific verb (get) plus resource (one bridge) plus the exact identifier (FHWA structure number, Item 8). This clearly separates it from the list/search siblings, which return sets rather than a single decoded record.

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 that structure numbers are unique only within a state and that passing state makes the lookup exact, which tells the agent how to use the optional parameter correctly. It stops short of naming an alternative tool for fuzzy or name-based lookups (e.g. search_bridges), which is the remaining gap.

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, so the description carries the burden; it discloses the return content (Poor-condition and posted/closed counts per county), which is useful for a tool with no output schema. It does not state read-only safety, ordering, or whether counties with zero bridges are included.

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?

One front-loaded sentence with the resource and returned metrics, zero 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 one-parameter read tool with no output schema, the description names the aggregate unit (per county) and the metrics returned, which is what an agent most needs. Minor gaps: no mention of county coverage or empty-county behavior.

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 100% with the single 'state' parameter documented and exemplified ('IL'). The description's 'for a state' reinforces scope but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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: per-county bridge counts for a state, including Poor-condition and posted/closed metrics. This is distinguishable from siblings like get_state_summary (statewide rollup) and list_bridges_in_county (per-county listings), though it doesn't name them explicitly.

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?

Usage is implied by 'for a state' – an agent can infer this is the aggregated county-level rollup rather than a raw bridge list. But there is no explicit when-to-use, no exclusion, and no alternative tool named.

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 well by enumerating what the summary contains and how omission of state changes the result. It does not mention access requirements, freshness, pagination, or response format, which are minor gaps for a read-only aggregate tool.

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 sentences, front-loaded with the primary use case and then the fallback behavior. Every clause adds useful information and there is no redundant exposition.

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 optional-parameter summary tool with no output schema, the description adequately explains what is returned in both modes. It could be slightly richer about data scope or freshness, but nothing essential for 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?

Schema coverage is 100%, so the parameter's format is already documented. The description adds value by explaining the semantic effect of omitting the optional state parameter, which the schema alone does not 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?

The description states a specific resource and scope: a bridge summary for one state, with an explicit fallback aggregate when no state is supplied. It distinguishes itself from sibling tools like get_county_summaries and get_bridge by naming the exact summary dimensions returned.

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 explains the two usage modes: pass a state to get that state's summary, or omit state to get totals for all states. It does not explicitly name alternatives such as get_county_summaries, but the mode selection is unambiguous.

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 whole burden, and it does disclose the meaningful behavior: the implicit condition = Poor filter and the two-key sort order, which an agent could not infer from the name. It says nothing about result size, whether limit is capped, or what each result contains, leaving the read/return profile thin.

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 clauses, front-loaded with the resource and filter, then ordering, then the trigger phrase. No filler, no restatement of the title.

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 two-parameter read-only query with no output schema, the description covers who it is for, what it filters on, and how results are ordered. The remaining gap is the undocumented limit parameter and the absence of any indication of result shape, which is modest for a tool this simple.

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 50%: state is documented in the schema and the description only repeats that it is required, while limit is undocumented in both places. The ordering rationale implicitly makes limit a top-N control, but the description never states that, so it neither harms nor compensates.

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 resource (the worst-rated bridges in a state) and defines 'worst' concretely as condition = Poor, ordered by lowest component rating then age. That operational definition separates it from generic siblings like search_bridges or list_posted_or_closed_bridges, though it never names those alternatives explicitly.

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 closing sentence gives an explicit trigger ('Use for worst bridges in X questions'), which is clear context for selection. It offers no exclusions or pointer to sibling tools for adjacent questions (e.g., posted/closed bridges), so it stops short of full routing 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?

No annotations are provided, so the description carries the full burden. It does disclose that results are paged, which is useful behavioral context, but says nothing about return fields, ordering, or what happens at page boundaries, and the limit/offset defaults are only in 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?

A single compact sentence with the scope front-loaded and zero filler. Slightly terse for a tool with four parameters, but nothing is wasted.

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 list tool with no output schema and no annotations, the description covers the essential scope and paging but leaves gaps around pagination semantics and response shape. It is adequate but not fully self-sufficient.

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 50%: state and county are documented, limit and offset are not. The description reinforces the county format ('3-digit FIPS county code') and the state+county pairing, but adds nothing for the undocumented paging parameters beyond the word 'paged'.

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 ('List bridges') plus a clear scope ('in one county'), which distinguishes it from siblings like get_state_summary or find_low_clearance_bridges. It does not explicitly name an alternative, but the county-level scope is a meaningful differentiator.

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?

Usage is implied by the scope constraint: use this when you want all bridges within a single county. However, there is no explicit when-to-use/when-not guidance and no mention of search_bridges or find_low_clearance_bridges as alternatives for filtered queries.

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 result ordering (worst condition first), the freshness limitation ('inspections can be up to ~24 months old'), and an authoritative-use caveat from FHWA. It does not mention pagination behavior or explicitly that this is a read-only listing, keeping it 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?

Two sentences, zero waste, with the core filter and ordering front-loaded before the caveat. Every clause 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 no-annotation, no-output-schema list tool, the description covers what counts as a match, result ordering, and a meaningful data-quality caveat. Missing pagination guidance and any hint of returned fields keeps it from a 5.

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 only 33% – only 'state' is documented in the schema. The description adds no information about 'limit' or 'offset' (defaults, max values, pagination semantics), so half the parameters are undocumented everywhere.

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 ('Bridges in a state') plus the exact filter semantics ('load-posted or closed to traffic (NBI Item 41 status P/R/K)') and ordering ('worst condition first'). This is far more precise than the sibling names alone, letting an agent distinguish it from get_worst_bridges or search_bridges without opening 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?

Provides use context ('relevant for routing and heavy-haul feasibility') and an important caution about NBI data not being authoritative for route clearance, but never names an alternative sibling or states when to prefer search_bridges or get_worst_bridges instead. Usage is implied rather than routed.

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 provided, the description carries the full burden and does so thoroughly: it declares read-only behavior, explains that data is the FHWA NBI 2025 snapshot rather than live status, notes that bridges without coordinates are excluded, and defines exactly what counts as a failure versus a warning.

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 dense but front-loaded and every sentence carries useful information for invoking the tool correctly. Despite its length, it does not waste space on restating the title or repeating schema fields without added meaning.

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, but the description explains the return shape: fails and warns arrays with fail_count and warn_count totals, ordered nearest first with distance_km. Combined with the failure/warning criteria and data-source caveats, this is complete enough to call the tool 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 100%, so the schema already documents all nine parameters. The description still adds useful operational semantics, especially that weight is compared against the bridge operating rating in metric tons, that height and weight alternatives are mutually exclusive, and that fails precede warnings in result ordering.

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 and resource: screening a corridor for a vehicle profile against bridge data. It also explicitly distinguishes itself from sibling tools by naming find_bridges_nearby and find_low_clearance_bridges and explaining the different inputs each expects.

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 explicit when-to-use guidance: use this instead of find_bridges_nearby when you have a corridor rather than a point, and instead of find_low_clearance_bridges when you have a full vehicle profile rather than a height threshold. It also clarifies this is not a router and does not produce directions.

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 does disclose output shape ('decoded records with condition rollup, posting status, clearances, and labels') and that this is a filtered search, but it says nothing about pagination behavior despite limit/offset params, result caps, or whether an empty scope is required to avoid full-table scans.

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 sentences: the first states purpose and scope, the second enumerates filters and the return payload. Dense but front-loaded with the identifying information; the filter list is long yet each item earns its place. Minor cost is a somewhat run-on enumeration.

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 13-param, zero-annotation, no-output-schema tool, the description covers purpose, scoping keys, all significant filters, and return contents. The remaining gaps are pagination semantics and any hint about result-size limits, which matter given the optional limit/offset.

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 only 46%, but the description compensates well: it names nearly every filter (state, county, condition, posting_status, owner_code, scour_critical, year_min/year_max, min_adt, route, q) and adds meaning the schema lacks, e.g. enumerating posting_status values and defining q against facility/feature/location fields. Only limit and offset go unmentioned.

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?

Specific verb+resource: 'Search US bridges in the FHWA National Bridge Inventory,' a concrete dataset and operation. It outlines the scoping dimensions (state/county/condition) that separate it from narrow siblings like get_worst_bridges or list_bridges_in_county, but never names those siblings explicitly, so differentiation is inferred rather than stated.

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 shows how to scope a query ('Scope with state, county... and/or condition') and lists optional filters, which implies when the tool is the right general-purpose search. It gives no explicit when-not guidance or named alternative for narrower cases (e.g., 'use find_bridges_nearby for radius queries'), leaving the agent to infer routing from the sibling names.

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