BuyAPI

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint:false. The description adds behavioral context about the data source ('reviewed public', 'recent curated') and clarifies the two operational modes, going 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 two sentences: the first states the core purpose, the second gives usage guidance and an exclusion. Every sentence earns its place; no fluff or redundancy.

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 low complexity (two optional parameters, no required inputs), comprehensive annotations, and an existing output schema, the description provides all necessary context: what it does, when to use it, and what not to use it for.

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 provides 100% coverage for both parameters (limit and vendorId), including descriptions. The tool description does not add parameter-specific semantics beyond what the schema already offers, so the 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 tool's function: 'Finds reviewed public stack examples related to a vendor, or recent curated stack examples.' It uses a specific verb ('finds') and resource ('stack examples'), and distinguishes from siblings by explicitly noting it is not a generic 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 provides explicit usage guidance: 'Use this when the user asks who uses a tool, what similar builders use, or wants examples of real stack combinations.' It also includes an exclusion: 'Do not use it as a generic recommendation tool,' implying an alternative such as stacks.recommend.

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, open-world, and idempotent behavior, so the bar is lower. The description adds that the tool performs both retrieval and ranking internally, and that it will output assumptions and unknowns, giving a sense of how complete the answer will be and where uncertainty lies. This is meaningful context beyond the annotations, though it does not describe every internal heuristic.

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, each with a distinct purpose: (1) what the tool does and its output, (2) when to use or avoid it, (3) a specific process note about vendors.resolve. No filler or repeated schema 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?

For a tool with 5 parameters and nested objects, the description is thorough: it explains the core function, delivery format, usage boundaries, and internal process. With an output schema present, it appropriately avoids detailing the return structure. The mention of 'from BuyAPI's corpus' and the assumption/unknowns behavior provides important context for decision-making.

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 has 100% coverage with substantive descriptions for all parameters (e.g., workload: 'Explicit workload assumptions...', constraints: 'Budget, scale, existing tools...'), so the description does not need to reiterate them. It reinforces that missing workload fields become assumptions, but this is already in the schema. The description adds minimal extra parameter-specific meaning.

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 the specific verb 'Recommends' and clearly identifies the resource ('complete stack') plus the key output components (decision matrix, cost estimate, assumptions, unknowns, alternatives, sources). It distinguishes from siblings by stating that this tool handles retrieval and ranking internally, so it is not a generic find/compare 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 guidance is given: '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') and instructs to avoid calling vendors.resolve first, clearly delimiting its scope 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the 'already-known' precondition but that is more usage guidance than behavioral detail. No new side effects, limitations, or rate limits are disclosed beyond the schema's note about workload assumptions (which lives in the schema description, not here).

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 that are front-loaded with the core function, then provide concrete examples and the alternative tool. Every word earns its place; no filler or redundancy.

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?

The description, combined with complete schema descriptions and a rich output schema, provides sufficient context for correct invocation. It covers the preconditions (already-known IDs), the decision context, and the fallback to vendors.resolve when the candidate set is unknown. The output schema handles return-value expectations.

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% (query, vendorIds, workload all have descriptions). The tool description adds no new meaning beyond echoing the idea of a 'specific workload or decision,' which aligns with the query/parameters but does not enrich them further.

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 'Compares two or more already-known BuyAPI vendors' with a specific verb and resource. It also distinguishes itself from siblings by specifying 'already-known' and referencing vendors.resolve for unnamed candidates.

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 provides when-to-use: 'Use this when the candidate set is known, for head-to-head questions...' and when-not-to-use: 'If the user has not named candidates, use vendors.resolve first.' Names the alternative tool.

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, open-world, and idempotent behavior, so the bar is lower. The description adds context about the specific categories of information retrieved (pricing, limits, gotchas, provenance) and the required preceding resolution step, which goes beyond what annotations state.

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 with no filler: the first sentence states the purpose, the second gives usage prerequisites and conditions. It is appropriately front-loaded and 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?

For a read-only, single-vendor details tool, the description sufficiently covers what it does, when to use it, and what to call first. The output schema exists, so return values are documented elsewhere, and annotations cover safety and idempotence, making this 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 both parameters are already documented in the schema. The description adds minimal extra value by giving a concrete vendorId example ('/database/supabase') in the usage guidance, but it does not explain the query parameter beyond the schema's existing description.

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 ('Retrieves') and a detailed resource ('detailed pricing, features, limits, gotchas, comparisons, and source provenance'), clearly distinguishing it from siblings by framing it as a follow-up tool for a single known vendor. It also explicitly ties it to the preceding step in a workflow (calling vendors.resolve first).

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 provides explicit when-to-use guidance: after a candidate is selected and the user needs claim-level details. It also gives a when-not/alternative by instructing to call vendors.resolve first unless the user already supplied a BuyAPI vendor ID, which directly addresses the sequential dependency with a sibling tool.

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 behavioral context beyond the annotations, such as 'Missing workload fields are returned as assumptions or unknowns instead of being hallucinated' and 'Treat results as BuyAPI claim-based estimate math.' This alerts the agent to the tool's honesty mechanism and the need for verification, which annotations do not 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?

The description is concise and front-loaded. The first sentence states the core purpose, and subsequent sentences provide essential caveats without redundancy. Every sentence adds value, and there is 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 not detailing the output schema, the description provides sufficient context for correct tool invocation: purpose, usage conditions, behavioral caveats, and verification guidance. The complexity is moderate, and the description covers all necessary aspects.

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 parameters are already well-documented. The description adds contextual meaning by emphasizing 'explicit workload inputs' and clarifying that missing fields become assumptions, which reinforces the intended use of the workload object. This slightly exceeds the baseline of 3.

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 'Produces directional monthly cost estimates from BuyAPI pricing data and explicit workload inputs.' This identifies a specific verb (produces), resource (cost estimates), and source (BuyAPI pricing + workload). It distinguishes itself from sibling tools, none of which focus on cost estimation.

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 provides explicit usage guidance: 'Use this only when the user asks for cost math and provides explicit workload inputs.' This tells the agent exactly when to invoke the tool and implies when not to use it. It also adds a caveat to verify exact billing with other sources, offering clear boundaries.

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 and idempotentHint, so the safety profile is clear. The description adds behavioral context by specifying 'recent reviewed' evidence rows, indicating recency and a review filter. It does not mention pagination or result ordering, but the output schema covers return structure, so this is sufficient.

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 two sentences, front-loaded with the core function, and the second sentence provides usage context. No wasted words, all information 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 moderate complexity (3 params, 2 required), comprehensive annotations, and an output schema, the description fully covers the tool's purpose, scope, and usage context. It even includes a direct use-case trigger and exclusions, making it complete for an agent to select 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 provides descriptions for all three parameters (limit, subjectId, subjectType), with 100% coverage. The description does not add further parameter-specific details, but it does implicitly map to subjectType via 'vendor, category, stack, or comparison.' Per the calibration baseline, a score of 3 is appropriate when 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 description clearly states the tool 'Returns recent reviewed BuyAPI evidence rows for a vendor, category, stack, or comparison.' It identifies a specific verb (returns), a resource (evidence rows), and the subject types (vendor, category, stack, comparison), distinguishing it from sibling tools like stacks.recommend 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?

The description explicitly says to use it when the user asks 'why BuyAPI believes something, what sources support a recommendation, or what recent human/source/opinion/history signals exist.' It also contrasts with the first recommendation tool, implying that recommendations should come from other tools and this one is for trust/provenance follow-up.

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 readOnlyHint and other annotations, the description adds meaningful behavioral context: it explains the response composition (ranked results, top-3 decision matrix with fit labels, confidence, tradeoffs, etc.) and the fallback behavior for out-of-corpus categories ('returns an explicit "not in corpus yet" result instead of inventing vendors'). This is transparent and reassuring, especially for a discovery/recommendation 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?

The description is well-structured and front-loaded: it opens with purpose ('First stop...'), then usage, then response details, then exclusions, then edge-case behavior. Each sentence contributes distinct information with no fluff or repetition. It is slightly longer than the calibration high example, but 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 and the presence of an output schema, the description is complete. It covers the tool's primary use case, expected output content, explicit exclusions, and the out-of-corpus fallback. This is sufficient context for an AI agent to decide when to invoke the tool and what to expect, even without viewing 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 description coverage is 100%, so baseline is 3. The description adds some value by advising 'provide category when known,' which highlights an important usage nuance not in the schema. However, it does not elaborate on the query parameter beyond what the schema already says, and the category parameter is fully documented in the schema. Thus, the description adds minimal additional 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's purpose with specific verbs: 'Finds BuyAPI vendor IDs' and 'category-specific vendor recommendations.' It explicitly distinguishes itself from siblings by being the 'First stop' and by describing its unique output (ranked results plus decision matrix), which differentiates it from vendors.compare, vendors.details, and other sibling 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: 'Use this when the user asks which provider in a category fits their constraints.' It also provides a when-not-to-use exclusion: 'Do not use this for local coding/debugging/docs questions unless they involve choosing a software vendor or tool.' However, it does not explicitly name alternative sibling tools for those cases, so it misses the 'alternatives' component of a 5.

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