Vendor Regulatory Evidence

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

The description directly contradicts the readOnlyHint annotation: 'Purchase' strongly implies a state-changing, potentially paid transaction, while readOnlyHint declares the operation has no side effects. This is a serious annotation contradiction that could mislead an agent about cost, reversibility, and safety.

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 short and front-loaded with the action, containing no filler. However, it is under-specified rather than deliberately structured, so its brevity is a result of minimalism rather than efficient communication.

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, a single undocumented parameter, and no explanation of cost, delivery, return value, or side effects, the definition is far from complete. The unresolved conflict between 'Purchase' and readOnlyHint further prevents an agent from safely understanding what will happen.

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 0%, and the description never mentions vendor_token, its meaning, format, how to obtain it, or its role in the purchase. The agent is left with only the parameter name and type, so the description adds no useful parameter-level 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?

The description uses a concrete verb ('Purchase') and a specific resource ('classified, source-backed vendor regulatory evidence package'), so the core purpose is identifiable. However, it does not explicitly distinguish this from sibling tools like get_vendor_regulatory_records or resolve_vendor, and the name says 'build' while the description says 'purchase'.

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 guidance on when to use this tool versus the sibling tools, nor any mention of prerequisites such as needing a vendor token or when an evidence package is appropriate. An agent would have to infer usage entirely from the tool name and the minimal description.

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 says 'Purchase,' which implies a transactional side effect such as a financial charge or acquisition action. This directly conflicts with the annotations readOnlyHint=true and idempotentHint=true, which state the operation is read-only and repeatable without side effects. This is a serious annotation 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 description is one dense sentence that front-loads the key information: action, data sources, normalization, and prerequisite. There is no redundant or filler wording.

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 tool, the description is almost sufficient, but the misleading 'Purchase' wording leaves the agent uncertain about side effects, cost, or whether this is truly read-only. With no output schema and no clarification of the purchase semantics, the definition is not complete enough for reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate. It partially does by linking the vendor_token to a 'resolved vendor,' but it does not explain the token format or how it is obtained. The guidance is helpful but minimal.

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 operation—purchase/obtain—and names the exact resources: normalized OSHA, EPA ECHO, and public SAM exclusion records. It also scopes the target to a 'resolved vendor,' which distinguishes it from sibling tools like resolve_vendor or build_vendor_evidence_package.

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 phrase 'for a resolved vendor' clearly establishes the prerequisite context: the vendor must already be resolved, implying use after resolve_vendor. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to decide when this tool is relevant.

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 readOnly, openWorld, and idempotent behavior. The description adds a distinct behavioral guarantee that ambiguity never creates a charge, which is exactly the kind of high-value context annotations do not express. There is 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?

Single compact sentence with two clauses; the main purpose is front-loaded and the charge-behavior clause earns its place. There is no fluff 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?

Despite strong annotations, the lack of an output schema and zero parameter documentation means an agent cannot predict the return shape or know how to supply fields like aliases, uei, or epa_frs_id. The description gives a high-level contract but not enough to invoke the tool correctly in all cases.

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 has no property descriptions (0% coverage) and the tool description does not explain company_name, state, aliases, uei, or any other parameter. An agent must infer meaning from field names alone, which is insufficient for eight parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: 'Resolve a U.S. vendor before payment.' This clearly distinguishes the tool from its siblings, which build evidence packages or fetch regulatory records, and conveys that its core job is vendor identity resolution.

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 phrase 'before payment' gives a clear when-to-use context, and 'ambiguity never creates a charge' adds a decision-relevant safety condition. However, it does not explicitly name alternatives or state when not to use the tool, so it falls just short of full usage guidance.

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