Verify a Company

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

Annotations already mark it read-only, idempotent, and non-destructive. The description adds sequencing requirements, result contents (cost and reason codes), and no-key/no-cost/latency context — all beyond what annotations provide, with no contradiction.

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 purpose is front-loaded in the first line, followed by compact WHEN/WHEN-NOT/COST/LATENCY sections. Each line carries operational information with 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?

Despite having no output schema, it names the return concept (OutcomeReceipt) and its key contents (cost, reason codes), explains the prerequisite workflow, and states access cost and latency. For a one-parameter read tool, this covers what an agent needs to call it 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?

The schema provides only a bare operation_id string with 0% description coverage. The description references a completed operation and implies the ID comes from get_status, but it does not explicitly define provenance or format; for a single self-explanatory parameter this is minimally adequate.

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 clear verb and object — retrieve the final OutcomeReceipt — and scopes it to completed operations. This distinguishes it from get_status by sequencing, so an agent can select it unambiguously.

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 and WHEN NOT TO USE sections name get_status as the prerequisite/alternative and forbid calling while pending/executing. This is exactly the guidance needed to avoid premature calls.

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 mark it read-only, idempotent, and non-destructive. The description adds the polling-frequency restriction, the webhook alternative, and cost/latency expectations, which are not encoded 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?

Four compact sections with a clear lead sentence and no filler. Each line carries distinct, useful information, and the most important usage guidance 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?

For a single-parameter read-only polling tool, the description covers purpose, usage, exclusions, and rate limiting. The only minor omission is a description of the response/status values, which matters slightly since no output schema is provided.

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

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

The schema only declares operation_id as a required string with no description. The description supplies the semantic context that it identifies an in-flight/pending async operation, telling the agent what the parameter refers to. It does not describe possible status values, but for a one-parameter tool the added meaning is sufficient.

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 the exact action (query current state), the resource (in-flight async operation), and the identifier (operation_id). This clearly distinguishes it from sibling tools like lookup_us_contracts or verify_company_record.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit WHEN TO USE and WHEN NOT TO USE sections tell the agent to poll only when no webhook has arrived, to avoid polling more than once per 10 seconds, and to prefer webhook delivery for real-time updates. This is the strongest possible usage 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds valuable behavioral context: zero cost, no API key required, ~1200ms latency, 2020-2026 data coverage, and top-award sorting by dollar amount. There is no contradiction with annotations, and the additional details go beyond what structured annotations provide.

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 longer than average but well-structured with headers, examples, and explicit use/not-use guidance. Virtually every section adds decision-relevant value, though the target-demand keyword list and repeated examples could be trimmed without losing critical meaning. Overall, it is appropriately organized and 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?

Given two simple parameters, no output schema, and rich annotations, the description covers all essential context: data source, return fields, coverage years, cost/latency, limitations, and alternatives. An agent has everything needed to invoke the tool correctly and interpret what comes back.

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%, with both company_name and max_results fully documented including default, min, max, and sorting behavior. The description itself does not add much parameter-level meaning beyond the schema, but example queries reinforce correct usage. Baseline 3 is appropriate because the schema already carries the semantic load.

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 uses a specific verb and resource: 'Search US federal contract awards by company (recipient) name using the free USASpending.gov public API.' It also clearly states what is returned and differentiates itself from siblings by explicitly excluding sanctions and verification use cases. An agent can immediately understand the tool's unique role.

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 includes dedicated 'WHEN TO USE' and 'WHEN NOT TO USE' sections, naming specific alternatives like verify_company_record and screen_sanctions. It also gives concrete example user queries that map directly to parameter values. This is exemplary guidance for tool selection.

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, and non-destructive. The description adds useful behavioral detail beyond those: exact price vs min/max range, no accuracy percentage promise, free/no key requirement, and ~100ms latency. This is exactly the kind of supplementary context annotations do not carry.

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

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

The description is front-loaded with the core return behavior, then uses compact sections for examples, when to use/not use, cost, and latency. Each part earns its place and there is no filler or tautology.

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 burden of explaining return values. It covers cost, latency, success probability, fixed vs range behavior, and the important caveat to check `cost_range`. It also addresses caching, authentication requirements, and latency, making it complete for an estimation 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 50%, so the description must compensate. It does so with concrete invocation examples showing `operation` and `params` shapes, and it clarifies that `params` mirrors the actual operation request body. The description does not enumerate valid operation values, but the examples and context provide enough for correct use.

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 uses a specific verb ('Return') and names the exact resource: cost, latency, and success-probability estimates for a proposed call. It also distinguishes fixed vs range outcomes, making it clear this is a pre-execution estimator rather than an actual execution or status tool.

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 sections say when to use it ('under a budget constraint... before proceeding') and when not to use it ('do not use in a hot loop... cache for at least 60 seconds'). This gives an agent actionable routing and exclusion guidance with no inference required.

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?

Beyond the readOnly/destructive annotations, it discloses why the UN list is excluded, that lists_screened reflects only lists that actually ran, that failed sources appear in sources_unavailable, and that reason_code is 'partial_screening' if any source is unavailable. It also warns never to fabricate a match or clear and instructs the agent to branch on screening_status rather than matched.

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 well-structured with clear sections and front-loads the core purpose before caveats and examples. It is longer than strictly necessary, with four similar example queries, but the length is largely purposeful given the multiple sanctions lists, failure modes, and disclaimers that need explicit handling.

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 takes on the burden of explaining return values and does so thoroughly: screening_status enum, matched, match details, lists_screened, sources_unavailable, reason_code, and partial-screening behavior. It also covers cost, latency, and use-case boundaries, giving an agent everything needed to call and interpret the tool correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the description does not need to compensate. The example queries add illustrative mappings from natural language to parameters, but the substantive semantics, such as country annotating/ranking without removing results, come from the schema itself. Thus the description adds only marginal parameter-level 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?

The description names a specific verb ('screening'), a specific resource (a name/entity against official sanctions lists), and enumerates exactly which lists are included (OFAC, EU, UK) and which is not (UN). This clearly distinguishes it from siblings like lookup_us_contracts and verify_company_record.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Dedicated WHEN TO USE and WHEN NOT TO USE sections give explicit trigger conditions (onboarding, payment, vendor engagement, due diligence) and explicit exclusions (not KYC/AML, not PEP/adverse media/credit risk, not bulk screening). It also names alternative screening domains and provides cost and latency considerations.

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?

The description adds substantial behavioral detail beyond the annotations: it runs exactly 6 internal checks, reports a count, does not test individual tools, is free, takes ~200ms, and should not be called more than once per minute. This goes well beyond the readOnly/idempotent/non-destructive hints.

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

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

The description is front-loaded with the core purpose, then provides concrete usage examples, when-to-use guidance, cost, latency, and rate-limit restrictions. Each section adds practical value without unnecessary fluff.

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 health-check tool with strong annotations and no output schema, the description covers everything an agent needs: what it does, what it does not do, when to use it, rate limits, cost, latency, and an example invocation. Nothing essential 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?

The tool has zero parameters and an empty schema, so there is little for the description to clarify. The description correctly implies the call takes no input by showing 'call self_test({})'. This is the appropriate baseline for a parameterless tool.

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 clearly identifies a specific verb and resource: 'Service health probe: runs 6 internal checks and reports how many passed.' It explicitly distinguishes itself by noting it does NOT probe each tool individually, which helps differentiate it from sibling data-lookup tools.

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 gives explicit WHEN TO USE guidance ('agent startup, before high-stakes task sequences, or after unexpected errors') and WHEN NOT TO USE ('Do not call more than once per minute'). It provides an example user query. It does not explicitly compare itself to sibling tools, but the scope is clear enough for selection.

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 mark this as read-only, idempotent, and non-destructive. The description adds meaningful behavioral depth: it never fabricates results, returns an honest not_found with the queried sources, and reveals cost and latency. This strongly informs an agent about side effects and reliability 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?

The description is longer than average but organized into labeled sections (WHEN TO USE, WHEN NOT TO USE, COST, LATENCY) and front-loaded with the core purpose. The example queries are valuable. Minor redundancy exists between the opening 'Free' and the COST line, but overall every section earns its place.

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

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

For a 3-parameter tool with no output schema, the description is complete: it states the data sources, return fields, not_found behavior, usage boundaries, cost, and latency. An agent has enough context to select this tool correctly and interpret the response even without an 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?

Input schema already covers all three parameters with descriptions, so baseline is 3. The description adds relational meaning: name is required and can be paired with an optional country filter, while LEI enables a direct precise lookup. The example user queries map natural-language utterances to concrete parameter combinations, which exceeds schema-only information.

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 verb+resource: 'Free, live lookup of a company official registry record.' It names the data sources (GLEIF, SEC EDGAR), the exact fields returned, and the not_found behavior, so an agent can clearly distinguish it from a generic search or a sanctions screen. The example queries further reinforce the intended scope.

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 scenarios (contract signing, vendor qualification, counterparty validation) and WHEN NOT TO USE exclusions (private companies not in GLEIF/SEC, exhaustive fraud detection). It does not name an alternative sibling tool like screen_sanctions, so it stops short of full alternative routing, but the guidance is clear and actionable.

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