BuyAPI

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that results are 'reviewed public' or 'recent curated,' which provides helpful context but no major new behavioral traits. No contradiction with 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 concise sentences with front-loaded purpose and usage. Every phrase earns its place; no wasted words.

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 the presence of an output schema and annotations, the description covers purpose, usage, and exclusions adequately. Missing a time frame for 'recent' but not critical for selection.

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 description of vendorId in the schema already defines it. The main description adds 'related to a vendor' which reinforces without extra detail. No additional semantics beyond 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?

The description clearly states the tool finds reviewed public stack examples related to a vendor or recent curated examples. It distinguishes itself from generic recommendation by saying 'Do not use it as a generic recommendation tool,' but does not explicitly name stacks.recommend as an alternative, leaving a slight gap.

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 usage context: 'when the user asks who uses a tool, what similar builders use, or wants examples of real stack combinations.' Also provides a negative directive: 'Do not use it as a generic recommendation tool.' Missing explicit mention of sibling tools as 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 indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds useful behavioral context, such as 'Do not pass source code or secrets' and clarifies that missing workload fields become assumptions, which goes beyond 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?

The description is three sentences with no redundancy. The main purpose is front-loaded. Every sentence adds value: purpose, usage guidelines, and a behavioral note. No wasted words.

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 that the tool has an output schema (context indicates 'Has output schema: true'), the description does not need to detail return values. It covers purpose, usage, parameters, and behavioral constraints comprehensively for a recommendation 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?

With 100% schema description coverage, baseline is 3. The description adds meaning beyond schema: for workload it explains 'Missing fields become assumptions, not fabricated precision'; for stackFacts it warns 'Do not pass source code or secrets'; for stackContext it says 'Agents should pass derived tool metadata only, not source code.' This adds semantic 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 clearly states the tool 'Recommends a complete stack from BuyAPI's corpus with a structured decision matrix, cost estimate, assumptions, unknowns, alternatives, and sources.' It uses a specific verb ('Recommends') and resource ('complete stack'), distinguishing it from siblings like stacks.findSimilar by emphasizing 'complete multi-layer stack choice'.

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 usage guidelines are provided: 'Use this when the user is starting a project or asks for a complete multi-layer stack choice.' It also states what not to use it for ('local coding/debugging/docs questions that do not involve software or vendor selection') and advises not to call vendors.resolve first.

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, idempotentHint, and destructiveHint; the description aligns by stating 'compares' without implying mutation. No contradiction, and the behavioral profile is clear from annotations. Minor credit for reinforcing the 'already-known' aspect.

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 concise sentences with no wasted words. Front-loaded with the core purpose and immediately followed by usage guidance.

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 the complexity (3 parameters, nested workload object, output schema present), the description fully covers purpose, usage, and alternatives. Output schema handles return structure, so no 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?

Schema coverage is 100%, so the schema already documents all parameters. The description adds context about vendors being 'already-known' but doesn't enhance parameter semantics beyond the schema. Baseline 3 is appropriate.

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 states the tool compares two or more already-known BuyAPI vendors for a specific workload or decision, using specific verb and resource. It differentiates from siblings like vendors.resolve by specifying 'already-known'.

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?

Explicitly states when to use ('when the candidate set is known') and provides a clear alternative ('use vendors.resolve first') if candidates are not named.

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 show readOnly, idempotent, not destructive. Description adds specifics about what data is retrieved (pricing, limits, etc.) and provenance, adding value beyond 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?

Concise two-sentence structure: first sentence states purpose and deliverables, second provides usage guidance. No wasted words.

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 parameters with full schema coverage, existing output schema, and annotations covering safety, the description is complete. It explains purpose, prerequisites, and usage without gaps.

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% with descriptions for both parameters. Description adds context: vendorId example (/database/supabase) and query param for focusing response, enhancing meaning beyond 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?

Description clearly states it is a follow-up tool for one known vendor, specifying it retrieves detailed pricing, features, limits, gotchas, comparisons, and provenance. It distinguishes from sibling tools like vendors.resolve (prerequisite) and vendors.compare (comparison).

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?

Explicitly tells when to use (after candidate selected, user needs details) and when to use vendors.resolve first unless user already has vendor ID. Provides clear context and 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?

The description adds useful behavioral context beyond annotations: missing workload fields are returned as assumptions or unknowns instead of being hallucinated, and results are directional. Annotations already declare readOnlyHint and idempotentHint, so the bar is lower, but the description still adds valuable transparency.

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 purpose and then provides usage guidelines in a compact paragraph. Every sentence adds value, though it could be slightly more concise.

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 the presence of an output schema (implied) and full parameter descriptions, the description covers purpose, usage, and behavioral expectations completely. 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?

Schema coverage is 100%, so the description does not need to repeat parameter details. It adds meaning by noting that missing workload fields become assumptions, which clarifies the behavior beyond the schema descriptions.

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 states it produces directional monthly cost estimates from BuyAPI pricing data and explicit workload inputs. This specific verb and resource distinguish it from sibling tools like vendors.compare or vendors.details.

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?

Explicitly states to use only when the user asks for cost math and provides explicit workload inputs. Also advises against using for exact billing and directs to verify with other sources, providing clear when-to-use and when-not-to-use 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 openWorldHint, providing strong transparency. The description adds context about returning 'recent reviewed' evidence, which aligns with the read-only nature. No contradictions.

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 three sentences long, with the most critical information (purpose) in the first sentence. Every sentence adds value: purpose, usage guidelines, and clarification. No unnecessary words.

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 the tool's simplicity (3 parameters, output schema present, rich annotations), the description covers purpose and usage adequately. The term 'recent' could be clarified, but overall the description completes the contextual picture without gaps.

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 parameters are fully described in the schema. The description reiterates the subjectType enum values but adds no new semantic information beyond what the schema already provides. Baseline score of 3 is appropriate.

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 states the action ('Returns'), the resource ('recent reviewed BuyAPI evidence rows'), and the scope ('for a vendor, category, stack, or comparison'). It distinguishes from sibling tools by labeling itself as a trust and provenance follow-up, not a first recommendation 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?

The description explicitly states when to use the tool ('when the user asks why BuyAPI believes something, what sources support a recommendation, or what recent human/source/opinion/history signals exist') and when not to use it ('not the first recommendation tool'). This provides clear usage context.

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 idempotentHint. The description adds value by detailing the response structure (ranked results, decision matrix) and the explicit 'not in corpus yet' result for uncovered categories. No contradictions.

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 compact paragraphs with no wasted words. The first sentence immediately conveys purpose, and the second adds behavioral nuance. Every sentence 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?

Given the tool's complexity (7 siblings, 2 parameters, output schema, and annotations), the description fully covers purpose, usage boundaries, behavioral details, and edge cases. No significant gaps.

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. The description adds meaning by listing the optional category values and clarifying that the query parameter is for 'relevance ranking'. This goes beyond the schema's descriptions, justifying a 4.

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 states it is the 'first stop' for category-specific vendor recommendations and ID discovery, using specific verbs like 'finds' and 'provide'. It distinguishes itself from siblings by being the primary entry point, and mentions specific outputs like ranked results and decision matrix.

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?

Explicitly states when to use: when a user asks which provider in a category fits their constraints. Also provides clear exclusions: not for local coding/debugging/docs unless involving choosing a software vendor. Additionally, explains behavior for out-of-corpus categories, preventing misuse.

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