CedarBid

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context: aggregation is by month across all years tracked, covering both counts and dollars, plus the fiscal-year timing observation.

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 what is returned and followed by a domain cue for interpreting the data. Both sentences earn their place, though the September claim is an unverifiable hard-coded assertion that could go stale.

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, no-output-schema aggregation tool, the description conveys the return shape (counts and dollars per month) and scope (all years tracked). Not stated: the actual year range, whether data is national or facility-level, and how missing months are represented.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies a fixed, unfiltered report with no user-supplied arguments.

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: monthly counts and dollar totals of VA HVAC/plumbing contract awards. The seasonal-fiscal framing separates it well from siblings like typical_prices or find_expiring_contracts, 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?

Usage is only implied via the September peak insight (useful for timing bids or planning around award season). There is no statement of when to use this versus alternatives such as typical_prices, and no exclusions or prerequisites.

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?

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the data coverage window (since October 2018) and the multi-match disambiguation behavior, which the agent would not otherwise know. It stops short of describing pagination or result caps.

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 what the tool returns and its scope, followed by input guidance and the ambiguity case. No filler or repetition.

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 carries the burden of describing returns and does so explicitly (totals, dollars obligated, active contracts, locations, recent contracts). Both parameters are covered and the disambiguation case is handled, so nothing needed 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 100%, so the baseline is 3. The description still adds meaning: it specifies the UEI is 12 characters and explains that a partial name can return a list of candidate matches, which clarifies the semantics of name_or_uei beyond 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?

States a specific verb (Shows), a precise resource (a company's VA HVAC and plumbing contracts), a temporal scope (since October 2018), and enumerates the returned aggregates. It is clearly distinguishable from siblings such as location_contracts or lookup_contract.

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?

Tells the agent how to invoke it (by company name or 12-character UEI) and what happens on ambiguous names. It gives clear usage context but never states when to prefer it over siblings like location_contracts or typical_prices, so no explicit exclusions or alternatives.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral value: the result ordering (soonest first), the domain rationale, and the returned fields (holder, dollars obligated, end date, bids received, official-record link). It omits any auth/rate-limit or result-count caveats, keeping it just 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?

Three dense sentences, front-loaded with what is listed and its ordering, then rationale, then filters, then return fields. No filler; each sentence adds distinct information an agent needs.

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 returned fields, and it covers the primary filters for a 6-parameter tool. Minor gaps remain around the limit/pagination behavior and default result count, but 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?

Schema description coverage is 83%, so the schema already documents nearly every parameter, including the set-aside enum and its 'last awarded under' nuance. The description restates the filter set (state, city, keyword, set-aside) and adds illustrative keywords, but no syntax or semantics beyond the schema; the 3 baseline 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 names a specific resource (recurring VA HVAC/plumbing service contracts), a precise scope (current period of performance ending within N months), and a sort order (soonest first). This is clearly distinct from siblings like lookup_contract or location_contracts, which retrieve rather than time-filter contracts.

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 supplies clear use context ('these are usually solicited again when they end'), telling the agent why and when to reach for it. It stops short of naming alternatives or stating exclusions (e.g., when to prefer buying_calendar or typical_prices), so it is context without 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the data window starts October 2018 and results include aggregates plus named top winners, which matters because there is no output schema. It does not contradict the annotations.

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 tightly written sentences with zero filler, front-loading what the tool returns before giving the use case. Nothing is wasted or buried.

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 enumerates what comes back (awards, dollars, top companies, recent contracts) and the historical window. The only meaningful omission is the meaning and default of the 'recent' parameter, which an agent would have to infer from the schema's default of 15.

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 67%: city and state are documented in the schema, while the 'recent' parameter has no description anywhere. The description reinforces the location scoping (city and state) but says nothing about the count/limit semantics of 'recent', so it neither fully compensates for the gap nor adds much beyond 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?

The description states a specific verb and resource (shows VA HVAC and plumbing contracts at one location) with a precise scope: aggregated awards/dollars since October 2018, top winning companies, and recent contracts. It is clearly distinguishable from company-oriented siblings like company_profile and lookup_contract, which slice the same data by vendor or individual contract rather than by facility.

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 offers a use case ('understand a facility before bidding') but gives no explicit when-not conditions or named alternatives among the siblings (e.g., when to use location_contracts vs. company_profile). 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that by enumerating what a successful call returns (holder, UEI, dollars obligated, dates, location, bids, set-aside, office, official record link). It does not say what happens on a miss or malformed PIID, which keeps it from 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?

One sentence, front-loaded with the operation and identifier, then a compact comma-delimited field list. No preamble, no filler, every clause carries information.

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?

Since there is no output schema, enumerating the returned fields is exactly the right compensation, and for a 1-parameter read-only lookup that is nearly everything an agent needs. Only the not-found / invalid-PIID behavior is left unstated.

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% and the schema's own example ('36C25225P1123') is identical to the one repeated in the description, so no meaning is added. Baseline 3 for a fully documented single parameter.

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?

Names a specific verb (returns details) and resource (a VA HVAC or plumbing contract) and pins the access method to a keyed identifier ('by its contract number (PIID)'). That keyed-lookup framing distinguishes it from the filter/aggregation siblings (find_expiring_contracts, location_contracts, typical_prices) without needing to name them.

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: an agent can infer this is the tool for an exact PIID, but the description never states when to prefer it over the sibling search tools or what to do when the PIID format is unknown. No exclusions, no prerequisites.

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?

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description layers on real behavioral context: the four-year contract window, the interquartile 'middle half' framing, the dollars-obligated unit, per-figure award counts, and the five-award minimum for state-level results. That is unusually rich disclosure of how the numbers are computed and suppressed.

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?

It is front-loaded: what is shown, then the statistical framing, then the geographic scoping rule, then the vocabulary. It is one very long sentence and the 14-item job-type run-on might arguably belong in the schema enum, but each clause carries genuine information for the caller.

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 carries the full burden of explaining returns, and it does: median, low/high bounds, dollars obligated, and the count behind each figure. Combined with the time window, geography threshold, and job-type list, an agent has everything needed to call and interpret this tool.

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 goes further by enumerating the full catalog of accepted job types (Air handling unit, Backflow, Boiler, Chiller, etc.) where the schema only offers the free-text example 'chiller' or 'backflow'. It also clarifies the dollars-obligated metric and the four-year lookback that no parameter documents.

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: it shows what the VA has typically paid per contract for a given type of HVAC/plumbing work. It also pins down the statistic (median and middle half of awards) and the time window, which cleanly separates it from siblings like lookup_contract or location_contracts.

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 an implicit usage condition ('for one state when it has at least five comparable awards'), which tells the agent when a state-level answer is even possible. However, it never says when to reach for this tool instead of buying_calendar, location_contracts, or lookup_contract, so the routing guidance is implied rather than explicit.

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