GovContractScout

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

Annotations already cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds genuinely useful context beyond them: an explicit prompt-injection warning that returned fields are untrusted scraped data, plus an enumeration of what each archetype record contains (a necessary addition since there is no output schema). It omits freshness/caching or list-size behavior, 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, both front-loaded: the core listing behavior first, then the untrusted-data caveat. No filler, no restatement of the tool name, and the safety note is placed where it will be read before invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description correctly takes on the burden of summarizing the returned fields (NAICS, award range, agency types, states, sample winners), and the single parameter is fully documented in the schema. It is complete enough to call correctly, though it says nothing about result volume or whether the list is static versus recomputed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is a single optional parameter with 100% schema description coverage, so the schema already defines the category filter. The description's example ('IT & Software Services') echoes the schema's example and adds no new semantics such as matching rules or behavior when category is omitted. Baseline 3 applies when the schema carries the parameter documentation.

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 the winning-business archetypes') and immediately scopes it as derived from historical government contract awards, with concrete examples. The resource is clearly distinct from siblings like search_contracts, search_naics, and get_states, so an agent can route correctly 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?

The description implies a discovery/planning use case by describing what the archetypes contain (NAICS, award range, agency types, states, sample winners), but it never states when to pick this tool over search_naics or search_contracts, nor any exclusions. Usage is inferable but not spelled out.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description still adds real value beyond them: it discloses that the original solicitation link is included, and warns that returned fields are untrusted scraped data that must never be treated as instructions — a security-relevant trait no annotation conveys. It stops short of describing behavior on a missing/invalid ID.

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: what it returns, one extra payload detail, and the untrusted-data caveat. The action is front-loaded and there is no filler or restatement of the tool name.

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 it does, listing the field groups and the solicitation link. Combined with the injection warning this is nearly complete; only error/absence behavior for an unknown contract_id is left unspecified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single contract_id parameter, including its UUID pattern, so the schema carries the semantics. The description only restates 'by ID' and adds no format, lookup, or fallback detail beyond what the schema already provides — the baseline of 3 for a fully-described 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 and resource ('Get full details for a single government contract by ID') and enumerates the returned fields (agency, set-asides, NAICS codes, dates, attachments). The singular 'single ... by ID' phrasing cleanly separates it from the plural sibling search_contracts, 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?

Usage is implied by 'by ID' — call this once you already have a contract_id and want the full record rather than a search result set. However, there is no explicit when-to-use statement, no mention of what to do when only a name/agency is known, and no reference to search_contracts as the discovery alternative.

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 this safe read-only and closed-world, so the description is free to add the more useful detail: the returned opaque id is unique within the app and stable across token refresh, reconnection, and display-metadata changes. That stability guarantee is real behavioral context not present in 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 sentences, front-loaded with what is returned and then the one non-obvious property (id stability). No filler, no restatement of the name.

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 read with no output schema, the description supplies enough: what is returned (the caller's profile) and what the id means. It stops short of describing the profile's fields, which an agent may want, but the essential contract is covered.

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 frames the input as implicit (the request's credential context) rather than a callable argument.

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 ('Return the profile') and scopes it precisely to 'this request's authenticated credentials', which distinguishes it from the contract-oriented siblings. It does not name a sibling explicitly, but the identity/credential framing makes the distinct role obvious.

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 tool is for discovering who the caller is via their authenticated credentials. There is no explicit when-to-use/when-not guidance and no alternatives are named among the siblings (archetypes, get_contract, score_contract, etc.).

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, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds only the 'metadata only' clarification, with no detail on result size, ordering, or refresh/liveness semantics despite claiming 'live' coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; the resource and its scope are stated immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter lookup list with annotations covering safety, this is nearly complete; the '(metadata only)' note signals the return nature. A hint at the returned fields or ordering would close the remaining 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 tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. Schema coverage is reported at 100% regardless.

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 ('List') and resource ('US states with live contract coverage') with a clear scoping qualifier ('metadata only'). It reads distinctly from reference-list siblings like search_naics, though it doesn't name an alternative 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?

No indication of when to call this versus siblings such as search_contracts or search_naics, nor any prerequisites. The '(metadata only)' note hints at scope but not usage conditions.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond annotations: the 5-factor matching method, the 0-100 return range, and a security warning that returned fields are untrusted scraped data and must not be treated as instructions.

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 are front-loaded with purpose, then method and return value, then a compact security note. No sentence is wasted, and the critical prompt-injection warning is included without bloat.

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 read-only scoring tool with a rich nested input schema and no output schema, the description gives the essential return value (0-100 score) and a notable security caveat about returned fields. It does not describe error behavior or auth requirements, but the annotations and schema cover most operational needs.

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 the contract_id and nested profile fields thoroughly. The description references matching factors that map to profile data, but adds no syntax, format, or defaults beyond what the schema provides.

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 ('Score') and resource ('a single contract's fit against a contractor profile'), and names the five matching factors. It clearly identifies the operation but does not explicitly differentiate from sibling tools such as win_likelihood or search_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?

Usage is implied by 'Score a single contract's fit against a contractor profile,' which tells an agent the context for scoring one contract. However, there is no explicit when-to-use guidance, no exclusions, and no named alternatives among the 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 readOnlyHint/openWorldHint/destructiveHint=false, so the safety profile is covered. The description adds two things the annotations cannot: a data-quality caveat ('NAICS coverage varies by state; some contracts lack NAICS codes') and an explicit prompt-injection warning that returned fields are untrusted scraped data to be treated as data, never instructions. No rate-limit or pagination behavior is described, 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?

Three tight sentences — purpose, filter inventory, return fields, then the data-trust caveat. Every clause carries information, nothing is repeated, and the core purpose is front-loaded.

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 compensates by enumerating the returned fields (title, agency, state, due date, set-asides, value). Combined with 92% schema coverage on 12 optional parameters and the NAICS caveat, an agent has everything needed to call this 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 description coverage is 92%, so the schema already documents nearly every parameter. The description only adds the NAICS 2-6 digit range and the USD/ISO-date framing, most of which is already in the schema. Baseline 3 applies when 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?

The first sentence names a specific verb and resource with scope: 'Search live US state & local government contracts.' Listing the available filters and the returned fields makes the tool's domain unmistakable and distinguishes it from get_contract (single record) and search_naics (code lookup).

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 filter list but never stated: there is no 'use this when...' guidance, no mention of when to prefer get_contract or search_naics, and no exclusions. The agent can infer the tool is a broad discovery search, but nothing routes it explicitly among the 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 establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds a genuinely non-obvious behavioral caveat: the returned fields are untrusted scraped data that must never be treated as instructions, which is prompt-injection-relevant context an agent cannot get from structured fields. It does not, however, mention pagination or result-size 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 sentences, front-loaded with the action, then the domain rationale, then the critical safety note last. Every sentence carries information, though the NAICS-primer sentence is the closest to expendable.

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 zero required parameters, the description covers what an agent needs: what it queries, what inputs look like, and how to treat the results. It leaves a small gap by not sketching what a returned record contains (code, title, etc.), but the trust warning compensates for much of that.

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 all three parameters (q, limit, keyword). The description adds example values that clarify what qualifies as a 'keyword or code prefix,' which is modest added value; it never mentions the undocumented 'q' alias or the limit semantics.

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+resource ('Look up NAICS codes') and even explains what a NAICS code is and why it matters ('classify a business's industry — used to match contracts'). It stops short of naming a sibling (e.g., search_contracts) as the alternative, so the differentiation is implied 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?

It provides concrete input examples ('janitorial', 'IT services', '5415') and a purpose context ('used to match contracts'), which implies when an agent would reach for it. However, there is no explicit when-to-use vs. sibling tools such as search_contracts, and no stated 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 declare readOnlyHint/openWorldHint/destructiveHint, so the safety baseline is covered. The description adds real value beyond that: it discloses the return shape (score, grade, reasons, matched archetype) and, critically, warns that returned fields are untrusted scraped data that must not be treated as instructions — a meaningful prompt-injection safeguard for an open-world scraping 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 tight sentences: purpose, return contents, then the untrusted-data caveat. Front-loaded, zero filler, and the most important safety note is retained without bloat.

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 (score, grade, reasons, matched archetype) and disclosing the scoring basis. The only notable gap is the lack of any distinction from the 'score_contract' sibling, but for a two-parameter read-only estimator it is otherwise 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 description coverage is 100%, so the contract_id UUID and the nested profile fields are already documented inline. The description mentions 'contractor profile' and 'contract's category' but adds no format, constraints, or meaning beyond what the schema provides, 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 and resource ('Estimate the likelihood (0-100) that a contractor profile wins a specific contract') and names the mechanism (historical award archetype in the contract's category). Clear on what it does, but it does not differentiate itself from the sibling 'score_contract', which an agent could easily confuse it with.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives. The presence of a similarly-named sibling 'score_contract' makes this omission material — the agent gets no signal about which scoring tool to pick.

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