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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantive context beyond them: MatchAwards data falls back to all agencies when the agency has none (with basis/sample indicating coverage), award records may be incomplete, ai text is AI-generated and must be labeled, and firms must not be called incumbents. It also specifies required output formatting (markdown links for url, sam_url, and each award's url/source_url).

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 trigger and the result payload, then parameters, then data caveats, then formatting, then exclusions — a logical order with no filler sentences. It is dense and long, but nearly every clause carries operational value; only the explicit listing of output contents overlaps the 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?

Even though an output schema exists, the description adds the interpretive layer an agent needs: the basis/sample caveat tells it how to phrase coverage honestly, and the incumbent/AI-generated rules prevent mischaracterization of results. Combined with the explicit exclusions and formatting requirements, nothing material is missing for correct invocation or reporting.

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% and each parameter already carries a description, so the baseline is 3. The prose restates the same guidance ('pass the id from a search result', 'my_naics up to 10 codes', 'my_set_aside to check the fit') without adding syntax or semantics beyond the 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?

States a specific verb (assess) and resource (one opportunity) and enumerates the output payload: days left, set-aside match, similar past awards at the same agency, the firms that usually win, and usual award value. It also names the sibling tools it is not (search_contracts, search_grants, find_teaming_partners), so an agent can route 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?

Opens with explicit trigger conditions ('when the user asks if one opportunity is a good fit, whether to bid, or wants a bid brief') and closes with explicit exclusions naming the alternative tools for searching, partner-finding, and job postings. When-to-use, when-not-to-use, and alternatives are all present.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: the 10-firm cap, the ranking logic and fallback order, that contact details are absent, that award records may be incomplete, and that ai_subcontracting is AI-generated and must be labeled. It also gives a hard usage rule ('Never call a firm the incumbent'), which is exactly the kind of behavioral constraint annotations cannot express.

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 but front-loaded: the trigger condition leads, followed by behavior, caveats, and exclusions. Most sentences earn their place, though it is on the long side and the markdown-link formatting instruction is a slightly jarring insertion mid-paragraph.

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 an output schema present, the description needn't explain return values, and it instead covers everything else an agent needs: fallback ordering, ranking, data-quality caveats, labeling rules, and the required URL formatting. Nothing material 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 both parameters are already fully documented, including the detailed role enum semantics. The description's 'Pass the id from a search result, and optionally role' largely restates the schema; the example id="117412688283576625" adds a small format cue. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('Find teaming partners... firms that won similar awards in the same state or at the same agency') with a precise scope. It distinguishes itself from sibling tools by naming search_awards and get_company as separate concerns. An agent can identify this tool 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?

Opens with an explicit trigger ('Use this when the user wants possible teaming partners... for one opportunity') and closes with explicit exclusions naming the alternatives ('Do not use for... search_awards... get_company... or for job postings'). Both when-to-use and when-not-to-use are covered with named siblings.

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 read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely non-obvious context: no contact details are returned, and award records may be incomplete so the agent should caveat results. It stops short of describing pagination or truncation of the top NAICS/agency lists.

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 when-to-use condition and keeps the exclusion last, which is good ordering. It is slightly long because it enumerates returned fields and adds a presentation instruction ('Print each recent award's url and source_url as markdown links'), but each sentence carries actionable content.

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 an output schema present, the description does not need to enumerate return values, yet it still lists them usefully and covers the main risk (incomplete records) plus the UEI provenance. Nothing critical for correct invocation is missing, although the return list is partly redundant with the output 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 coverage is 100% and the schema already supplies the pattern and the exact same example ('C3KXNLTAAY98'). The description's only addition is provenance ('e.g. from a search_awards row'), which is mildly useful but does not go beyond the schema in any substantive way, 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 ('one firm's government award history') and explicitly scopes it to when the UEI is known. It distinguishes itself from search_awards by naming the alternative for name/NAICS lookup, 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?

Gives an explicit trigger ('when the user wants one firm's ... and its UEI is known, e.g. from a search_awards row') plus explicit exclusions ('Do not use for finding firms by name or NAICS (search_awards) or for contact details'). Both the when and the when-not are named with their 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 readOnly/idempotent/non-destructive, and the description adds substantially more: the 2000-character truncation of description, that AI notes are optional ('when MatchAwards has them'), and a required labeling caveat for AI-generated text. It also specifies output presentation duties (markdown links for url/sam_url), which annotations cannot convey.

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 when-to-use sentence, followed by ordered operational notes (id provenance, return contents, AI labeling, link formatting, exclusions). Every sentence is actionable, though the formatting directive is a slight extension beyond core tool semantics.

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?

An output schema exists, yet the description still summarizes the payload and flags the AI-generated caveat, which is the one thing an agent could misuse. Combined with explicit routing to siblings, an agent has everything needed to call this 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% and the pattern is documented, so the description only needs to add value; it does by stating the id must come from a search result and giving a concrete example id. Marginal gain over the schema, so not 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 ('details of one search result') and explicitly scopes what is returned (row, description up to 2000 chars, contacts, optional AI notes). It is clearly distinguishable from search_* and assess_opportunity because it retrieves a single known id rather than searching or evaluating.

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 an explicit trigger ('when the user wants the details of one search result, or who to contact about it'), explicit anti-triggers (not for searching, not for fit/bid questions, not for deeper contact details), and names the alternatives to use instead (search_contracts, search_grants, search_jobs, assess_opportunity).

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 readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description goes beyond them by disclosing ranking behavior ('common terms such as cybersecurity or janitorial list their usual codes first'), prefix-expansion behavior for digits, and a required output presentation step (print each opportunities_url as a markdown link).

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 triggering condition and free of filler, but the middle paragraph is tightly packed and mixes query semantics, limits, and cross-tool routing into dense clauses. Still, every sentence 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?

An output schema exists so return values need no explanation, annotations cover the safety profile, and the description supplies usage triggers, query semantics, routing to consumers, and output formatting. Nothing an agent needs to call this 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 baseline is 3, but the description adds real meaning beyond the schema: the 2-100 character bound is restated with a concrete purpose, and it explains that a 2-6 digit query returns every six-digit code starting with those digits. The 'usual codes first' ordering for common words is also semantics the schema does not carry.

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 names a specific verb+resource (look up a NAICS code) and states the two triggering intents: describing a line of work in words, or asking what a code/prefix covers. It is clearly distinguishable from the sibling search_* tools, which it explicitly routes codes to.

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 explicit when-to-use ('the user describes a line of work in words and a NAICS code is needed'), explicit when-not-to-use ('Do not use for searching opportunities or awards themselves'), and names the alternative tools to hand codes to. Nothing 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words on what annotations cannot express: pagination behavior ('If has_more is true, call again with cursor=next_cursor and the same filters'), a data-quality caveat ('Award records may be incomplete, so say so'), and the agency-name fuzzy-match note. That is substantive behavioral context beyond the structured fields.

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 purpose sentence, then a tight filter inventory with defaults, then pagination, then caveats and routing exclusions. It is long, but every block carries distinct information and the trailing markdown-link instruction is a concrete output requirement rather than 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?

An output schema exists, so return values rightly go unexplained, yet the description still covers the operational essentials an agent needs: has_more/next_cursor continuation, ambiguous-agency handling, incomplete-record disclosure, and the sibling boundary. For a 10-parameter open search with 0 required parameters, that is complete.

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 semantics the schema does not: a grant award's title is its recipient's name (which changes how keyword behaves), the matched_naics/matched-agency result notes, and the guidance to batch several NAICS codes in one call. It re-enumerates the filters somewhat redundantly, keeping it at 4 rather than 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?

'past awards by NAICS, agency, state, awardee name or UEI, with amounts and dates' is a specific verb+resource+filter scope, and the description explicitly contrasts itself with search_contracts, search_grants and get_company, so it is distinguishable from siblings 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?

It states the triggering condition ('when the user asks who won government contracts or grants') and names the exclusions with the alternatives to use instead ('Do not use for open opportunities to bid on (search_contracts, search_grants) or for one firm's history when its UEI is known (get_company)'). Nothing 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?

Annotations already declare readOnly/idempotent/non-destructive, so the description correctly spends its words elsewhere: it discloses the pagination contract (has_more, next_cursor, same filters) and the effective default open=true that the schema alone leaves as null. It also discloses two behaviors invisible in structured fields — that agency names are matched to the closest MatchAwards agency and reflected in the result note, and that results should be rendered as markdown links with sam_url for federal notices. Minor gap: no note on result volume or latency expectations.

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 purpose, then a compact filters block, then pagination, then presentation, then exclusions — a sensible order with no filler. The filter enumeration largely duplicates the schema and is the one section that could be trimmed without loss.

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 10-parameter tool with an output schema and rich annotations, everything an agent needs is present: routing in and out, filter interactions that surprise people (state skips federal notices without one, set_aside is federal-only), the paging loop, and output presentation. Return shape is correctly left to the output 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 coverage is 100%, so the schema already documents every parameter including the deadline-based meaning of open and the NAICS pattern. The description mostly restates the same list; the genuine additions are the example, "Pass several NAICS codes in one call", and stating open's effective default as true where the schema shows default null. That is real but incremental value over a fully documented schema, so the baseline 3 is right.

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?

"Use this when the user wants US federal or state government contract opportunities to bid on: bids, RFPs, solicitations, set-asides" gives a specific verb-plus-resource plus the vocabulary an agent will actually see from users. It names the exact siblings it is not (search_grants, search_jobs, get_opportunity), so routing is unambiguous 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 clause up front, explicit exclusions mapped to named alternatives (grants, jobs, single-record details), and an explicit continuation rule for pagination with has_more/cursor. A worked example (naics="238160", state="VA", keyword="roof") anchors the intended call shape.

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 establish read-only, idempotent, closed-world behavior, but the description adds real operational context not in annotations: cursor/has_more pagination protocol, the warning that open status can lag so response_deadline should be checked, and that grant notices carry no state. The one weak spot is the phrase 'open grants of any age', which is vaguer and looser than the schema's precise deadline-based definition (no deadline counts as closed).

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 trigger, then a compact filter summary, pagination rule, a caveat, output formatting, and exclusions — each block earns its place. The parenthetical filter list mildly duplicates the schema's field descriptions but functions as a single-glance summary rather than padding.

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?

An output schema exists, so return values need not be enumerated, yet the description still covers the one thing the schema cannot: the pagination loop (has_more/next_cursor with identical filters) and result presentation. For a six-parameter, zero-required search tool, an agent has everything needed to call it correctly on the first and subsequent pages.

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 value by flagging keyword as title-only, restating the 1-180/1-50 bounds as quick reference, and adding the strategy hint 'pass several NAICS codes in one call' that is absent from the schema. No added detail on how posted_within_days interacts with open, hence not 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?

Opening line names a specific verb (search) and resource (US federal grants/funding opportunities), and the closing line explicitly separates it from search_contracts and search_jobs. An agent can route correctly without inspecting 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 an explicit when-to-use trigger ('when the user wants US federal grants'), explicit exclusions with named alternative tools for contracts and jobs, plus operational guidance to batch NAICS codes in one call. Nothing 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the burden is lighter. The description still adds value beyond them: the pagination contract via has_more/next_cursor, the filter semantics (state filter drops records with no state), and the presentation instruction to emit urls as markdown links. It does not disclose rate limits or result-ordering 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?

Front-loaded with the trigger condition, then a compact filter list, then return fields, then pagination, then exclusions. Every sentence carries a distinct instruction and none are redundant with each other.

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 an output schema present, the description need not enumerate return shapes, yet it still names the key row fields for planning. Pagination, filter interactions, and routing to sibling tools are all covered, leaving nothing an agent needs to call this 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 baseline is 3, but the description adds operational guidance the schema lacks: the example values, the instruction to pass several NAICS codes in one call, and the note that matched_naics identifies which code hit. It also clarifies that 'agency' means the employer, which is not derivable from the schema alone.

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?

Opens with a specific trigger ('the user is looking for a job, or for hiring signals') plus a concrete resource and scope ('postings from the last 30 days'). It also names the sibling tools it is not (search_contracts, search_grants), so an agent can disambiguate without opening schemas.

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, explicit when-not-to-use with the alternative tools named, and a worked example (keyword="electrician", state="TX"). The pagination rule ('call again with cursor=next_cursor and the same filters') is a clear operational condition.

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