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 well: it discloses the record limit, the CSV column contract, and the precedence rule that csv_content overrides addresses. It stops short of permissions, error/partial-match handling, or rate limits, which matter for a 10k-record batch call.

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, front-loaded with the capability and limit, then input format, then return format. Every sentence carries information, though the return-field list is long and could be tightened.

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 properly enumerates the returned CSV columns, and it covers both input shapes plus the precedence rule and the batch ceiling. Only the response/error semantics for unmatched addresses are left unaddressed.

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 100%, so the baseline is 3. The description adds the CSV column ordering and the PR Urbanization variant beyond what the schema states, but it does not explain the vintage or benchmark defaults that the schema itself documents only lightly.

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 plus scope: batch geocode up to 10,000 addresses and return Census geographies, with the exact geography levels named (State, County, Tract, Block). It implicitly separates itself from single-address siblings, but never names an alternative tool, so an agent must infer the batch/one-line split from the name alone.

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 context is implied by scope and by the two accepted input shapes (raw CSV or structured array), and the 10,000 record ceiling is stated. There is no explicit when-to-use versus when-not guidance and no mention of the other batch siblings (batch_geocode_locations, batch_geolookup_coordinates), so selection between them is left to inference.

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 behavioral burden. It discloses the key behavioral traits: 10,000 address cap, locations-only restriction, input format options, and precedence rules ('Takes precedence over the addresses array'). It also enumerates the return CSV columns. Missing details on error handling or rate limits, but substantial for an unannotated 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?

The description is dense yet well-structured, front-loading the core action and limits, then detailing input formats and output columns in a compact way. Every sentence adds value without redundancy.

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?

Despite no output schema, the description fully specifies the return CSV columns, and with 100% schema coverage for params, it leaves no critical gaps for correct usage. It adequately covers input formats, limits, and output structure.

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 parameters. The description adds meaningful context beyond the schema by detailing the exact CSV format expected (UniqueID,Street,City,State,ZIP) and precedence between csv_content and addresses, which aids correct invocation.

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 (geocode) and resource (addresses, locations only) with a clear scope limit ('no Census geographies'). This distinguishes it from sibling batch_geocode_geographies and the oneline/parsed geocode tools by its batch + locations-only nature.

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 implies usage for bulk location geocoding and hints at format choices, but does not explicitly say when to use this vs single-address siblings (geocode_oneline_address, geocode_parsed_address) or when to prefer CSV over array input beyond precedence. No 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, the description carries the full burden; it does disclose the 10,000-record ceiling and the fields returned, which is real value. However, it omits behavioral considerations that matter for a batch lookup: geographic coverage limits, auth/rate-limit behavior, and whether out-of-range or unmatched coordinates fail the whole batch or are simply omitted.

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 tight sentences, front-loaded with purpose, then input modes, then return values. Slightly less than perfect because the CSV column format is repeated from the schema's csv_content description.

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 4-parameter batch tool with no annotations and no output schema, listing the returned geography codes is helpful, but the description leaves out coverage restrictions, failure/partial-success semantics, and any guidance on the vintage/benchmark parameters' effect on results.

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 100%, so the schema already documents vintage, benchmark, coordinates, and csv_content including the precedence rule. The description restates the CSV column format, which adds mild convenience but no new semantics; 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?

The description gives a specific verb and resource ('Batch look up Census geographies'), and the coordinate-pair scope plus the 10,000 cap distinguishes it from the single-coordinate sibling find_geographies_coordinates. It stops short of naming that sibling or batch_geocode_locations explicitly, so an agent must infer the split.

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 context is implied by the batch framing and by the two accepted input forms (raw CSV vs structured array), but there is no explicit when-to-use vs when-to-use-single, no prerequisite or coverage caveat (e.g. US-only), and no guidance on choosing between csv_content and coordinates.

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 the breadth of the returned geography layers, which is genuinely useful given there is no output schema, but it says nothing about auth requirements, rate limits, error behavior for out-of-range or non-US coordinates, or whether layer/vintage choices affect results.

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 core lookup action and followed by the payload summary. The long enumeration of layers is slightly bulky but earns its place as a substitute for a missing output schema.

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 100% schema coverage and no output schema, the description sensibly summarizes the return payload. It is close to complete, missing only edge-case behavior (invalid coordinates, non-US locations) and any guidance on the optional layers/vintage/benchmark parameters.

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 100%, so latitude, longitude, layers, vintage, and benchmark are already documented in the schema with formats and defaults. The description adds no syntax or semantics beyond the schema, so the baseline of 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 and resource ('look up Census geographies') and names the exact input ('a given longitude/latitude coordinate pair'). This implicitly separates it from the address-based siblings (find_geographies_oneline, find_geographies_parsed, find_geographies_pr), which take addresses rather than raw coordinates.

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 coordinate input implies the use case, but the description never states when to choose this over find_geographies_oneline or find_geographies_parsed, nor any prerequisite such as US-only coverage. Usage is left to inference from the parameter list.

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 behavioral burden. It discloses the class of geography returned but says nothing about output shape, US-only scope, match-accuracy/no-match behavior, or rate limits. Additionally, 'Requires a benchmark and vintage' conflicts with the schema, where both are optional fields with defaults (Current_Current, Public_AR_Current), which could push an agent to supply parameters unnecessarily.

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 front-loaded sentences: the core action first, prerequisites second. The long parenthetical layer list is informative rather than filler, though it is heavier 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 should carry more of the return-value and caveat load. It communicates the domain of results (Census geographies) adequately but omits output structure, geographic coverage limits, and failure behavior for a geocode-plus-enrichment call.

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 100%, so all four parameters are already documented in the schema (including the layers enumeration and defaults). The description only echoes the layers concept and the benchmark/vintage mention, adding essentially no syntax or format detail beyond the schema. Baseline 3 is 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?

Specific verb+resource: geocodes a one-line address AND returns the associated Census geographies, with an explicit enumeration of what geographies (States, Counties, Tracts, Blocks, CDs, etc.). The 'one-line address' phrasing distinguishes it from find_geographies_parsed and geocode_pr_address without needing to open 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?

The 'one-line address' framing implies when this variant applies versus the parsed/PR siblings, and it flags that a benchmark and vintage are involved. However, it names no alternative explicitly and gives no guidance on when to choose find_geographies_oneline over geocode_oneline_address or find_geographies_coordinates.

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 must carry the behavioral load. It discloses the required input combination and the PR limitation, but says nothing about return shape, layer defaults, vintage/benchmark behavior, or error conditions for a 7-parameter query 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 short sentences, zero filler. The core capability leads, the input precondition follows, and the exclusion is last.

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 7-parameter tool with no annotations and no output schema, the description covers input requirements and one exclusion but omits return content, the role of layers/vintage/benchmark, and any default or pagination 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%, so per-parameter meaning is already handled. The description still adds a cross-parameter constraint the schema cannot express: only 'street' is required in the schema, yet the description requires zip OR city+state alongside it. That is real added semantic value.

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 compound verb+resource: geocode a parsed US address AND return Census geographies. The word 'parsed' cleanly separates it from find_geographies_oneline and find_geographies_coordinates, and 'geographies' separates it from geocode_parsed_address.

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 input precondition (street + zip, or street + city + state) and an explicit exclusion (no Puerto Rico Urbanization/Municipio). It implies but does not name the sibling to use instead (find_geographies_oneline for unparsed input, find_geographies_pr for PR), so it falls just short of the top band.

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 full burden. It only states that it geocodes and returns geographies, omitting read-only nature, rate limits, accuracy, error handling, or output format. For a geocoding tool with zero annotation coverage, this is a significant gap.

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 with zero waste: the first front-loads the purpose and return content; the second specifies input requirements. Every sentence 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?

Covers purpose and input requirements adequately, but with no output schema and no annotations, it should describe return values and behavioral traits more fully. Missing when-to-use versus siblings and details about the returned geographies.

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 100%, so the baseline is 3. The description meaningfully adds required combinations (street + zip OR street + city + state; or street + urb + municipio) beyond the schema, which only marks 'street' as required. This clarifies how to supply 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?

States a specific verb ('Geocode') and resource ('Puerto Rico address') and notes it returns census geographies, distinguishing it from geocode_pr_address. However, it does not explicitly name or differentiate from sibling find_geographies_oneline, find_geographies_parsed, or find_geographies_coordinates.

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 minimum input combinations for submission, which is helpful, but offers no guidance on when to use this tool versus sibling find_geographies_* tools or geocode_pr_address. No exclusions or alternative selection criteria are given.

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 behavioral burden. It usefully discloses the return payload (matched address, interpolated coordinates, Tigerline ID, range components) but says nothing about error behavior for unmatched addresses, rate limits, or the benchmark default's effect. Geocoding is inherently read-only, so the omission of safety disclosure is less damaging than it would be for a mutation 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 action, followed by return values. The inline example partially duplicates the schema's example, which is a small redundancy, but no sentence 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?

With no output schema, the description correctly compensates by enumerating the returned fields, and both parameters are documented in the schema. The main remaining gap is failure/edge-case behavior for addresses that do not match.

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 already 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: missing city/state/ZIP fields may be omitted or represented by bare commas, which is not stated in the schema. The benchmark parameter is left entirely to the schema, keeping this short of a 5.

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 ('Geocode a single address provided as one line') and gives a concrete example. The 'single address / one line' framing implicitly separates it from batch_geocode_* and geocode_parsed_address, though it never names those siblings 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 only implied: the 'one line' phrasing tells the agent this is for unparsed input, but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. geocode_parsed_address for structured fields). The note on omitted city/state/ZIP is format guidance, not 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?

With no annotations, the description carries the full disclosure burden; it does well by listing the returned fields (matched address, interpolated coordinates, Tigerline ID, address range components) and the unsupported address type. It stops short of noting error behavior, network/auth requirements, or how unmatched addresses are reported.

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 sentences, front-loaded with purpose, then input requirements, then the exclusion. Every sentence carries information an agent needs; nothing is wasted or repeated.

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 the description compensates by enumerating the returned components, so an agent knows what to expect back. Input requirements and the unsupported PR case are also covered, leaving no material gap for a single-address geocoder.

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 100%, so the baseline is 3. The description goes beyond the schema by explaining the conditional combination requirement (street+zip vs street+city+state), which the schema alone only expresses as a single required 'street' field. It adds no detail on the benchmark parameter or coordinate precision.

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 (geocode) and resource (a single US address with fields parsed into separate components), which also differentiates it from the sibling geocode_oneline_address. The return payload (matched address, interpolated coordinates, Tigerline ID, range components) is named up front, so the agent knows exactly what this tool produces.

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 concrete input conditions ('street and zip OR street, city, and state must be provided') and a negative scope boundary ('Does NOT support Puerto Rico addresses with Urbanization/Municipio'). It does not explicitly name the alternative tool to use for those PR cases (geocode_pr_address), so the routing is implied rather than 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?

No annotations exist, so the description carries the full burden. It usefully discloses that state is always PR and the real field-combination requirements (beyond the schema's misleadingly minimal 'street only'), but says nothing about return values, match quality, or error 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?

Three tight sentences, each earning its place, with the core purpose front-loaded and the input rules following immediately. 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 fully covers input requirements but leaves the return value undocumented. For a geocoding tool this is a moderate gap, though the standard geocode response makes it tolerable.

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 value the schema cannot express: the conditional dependency between parameters (street+zip OR street+city, or street+urb+municipio) and the implied constant 'state = PR' that is not even a schema property.

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 ('Geocode a single Puerto Rico address') and names the distinguishing features (Urbanization, Municipio support). It differentiates itself by PR-specificity, though it does not explicitly contrast with siblings like geocode_parsed_address or geocode_oneline_address.

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 concrete input-combination rules for two scenarios (with and without Urbanization), which implies how to invoke the tool. However, it never states when to prefer this tool over the sibling geocoders, nor any exclusions, so usage is only partially guided.

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 behavioral burden. It only says it lists all available benchmarks; it does not state that this is a safe read-only operation, nor does it mention pagination, rate limits, or any auth requirements. The domain explanation is helpful but not 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?

Two efficient sentences, front-loaded with the action, followed by a useful definition. Every sentence earns its place with no redundancy.

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 parameterless list tool with no output schema, the description provides adequate domain context. It could be more complete by hinting at the return shape (e.g., a list of benchmark IDs) or any usage constraints, but it is sufficient for correct invocation.

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 per calibration the baseline is 4. There are no parameter semantics to document, and the description does not need to compensate for any 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 ('List') and resource ('benchmarks for the Census Geocoder'), and defines what a benchmark is with concrete examples. It does not explicitly differentiate from the sibling list_vintages, but the distinct resource makes confusion unlikely.

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?

No when-to-use guidance, no alternatives named, no prerequisites or sequencing relative to the geocoding tools. The definition of a benchmark is domain context, not invocation 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, the description carries the full behavioral burden. It discloses what vintages represent and gives examples (Current_Current, Census2020_Current), but says nothing about return shape, ordering, or error behavior. For a simple input-driven lookup this is adequate but 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 sentences, front-loaded with the purpose, then definition, then the usage trigger. Every sentence carries information, with no redundancy.

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 list tool with 100% schema coverage and no output schema, the description covers purpose, semantics, and when it is required. Only return-shape expectations remain unaddressed, which is minor here.

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 100% – the schema already documents the benchmark parameter and points to list_benchmarks. The description adds no syntax or format guidance beyond what structured data provides, so the baseline of 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?

The description states a specific verb and resource ('List all available vintages for a given benchmark') and clarifies what a vintage actually is. It is clearly distinguishable from the geocode/find_geographies siblings, though it does not explicitly name a sibling it is not.

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 explicitly states the selection condition: vintages are 'Required when using Find Geographies endpoints,' which tells the agent exactly when this lookup matters. It stops short of naming alternatives or when-not-to-use conditions, but the core trigger is clear.

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