discovery

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

While annotations already indicate a non-read-only operation (readOnlyHint=false), the description adds meaningful behavioral context: activation 'start[s] serving' and requires a creative to be submitted first. The output_format also specifies the return value ('Activated media buy with won_at timestamp'), providing transparency beyond the annotations. It does not contradict any 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 efficiently structured into short labeled sections (tool_description, when_to_use, combination_hints, output_format), with no wasted words. Every section adds distinct value and is easy to scan.

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 simple mutation tool with one parameter and no output schema, the description is complete: it explains what the tool does, when to use it, what must happen before, what happens after, and what the response will be. The combination_hints also integrate it into the broader workflow, covering the tool's context comprehensively.

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 single parameter media_buy_id is fully documented in the input schema (100% coverage), including its type and description. The tool description does not add further parameter-specific details beyond what the schema already provides, so 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 states a specific action: 'Activate an approved media buy to start serving.' It clearly identifies the verb (activate), resource (media buy), and the intended effect, effectively distinguishing it from sibling tools like pause, cancel, and submit_creatives.

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 'when_to_use' section explicitly states 'After submit_creatives, when ready to go live with the campaign,' and the description notes the prerequisite 'Requires creative to be submitted first.' The combination_hints further clarify the sequence and mention alternatives (pause, cancel), making usage guidance explicit.

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?

Discloses key behaviors: terminal state, irreversibility, release of remaining budget, and output format. These go beyond the annotations (e.g., idempotentHint, destructiveHint) and provide critical context for invocation. 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?

Structured into clear sections (tool_description, when_to_use, combination_hints, output_format) with minimal fluff. Slight redundancy in repeatedly stating terminal/irreversible, but overall efficient and front-loaded with purpose.

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?

Complete for the tool's complexity. Covers purpose, usage timing, behavior, and output. With siblings like pause and activate, the distinction is clear. No return schema exists, but the output_format section adequately describes the response.

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 both parameters, each with clear descriptions (reason, media_buy_id). The tool description does not add parameter-specific semantics beyond the schema, but baseline 3 is appropriate as the schema carries the burden.

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: 'Cancel a media buy campaign.' It also specifies the terminal nature, distinguishing it from temporary operations like pause. The verb+resource is specific and unambiguous.

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 guidance: 'When an advertiser wants to permanently stop a campaign. Cannot be undone. Use pause for temporary stops.' This directly addresses alternatives and exclusions, making it easy for an agent to decide between cancel and pause.

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 annotations (readOnlyHint=false, idempotentHint=false), the description reveals that this tool 'creates a binding commitment' and must be confirmed with the user. It also explains the validation/auction scoring behavior and return status (approved/rejected). The score formula and rejection-reason hint add further behavioral context.

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 into useful sections (tool_description, when_to_use, combination_hints, output_format) and is appropriately sized for an 18-parameter tool. The score formula and combination hints are relevant, though there is minor redundancy between tool_description and output_format regarding return status.

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 complex creation tool with no output schema, the description is highly complete. It covers purpose, prerequisites, output fields, workflow sequencing with siblings, failure handling (rejection_reason), and the scoring formula. It enables an agent to understand the tool's role fully.

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 baseline is 3. The description adds minor semantic value by referencing 'bid', 'quality', and 'context' in the score formula, but does not provide additional explanation for individual parameters beyond what the schema already offers.

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 verb 'Create' and the resource 'media buy (bid on publisher inventory)', and explains what it does: 'Validates rules, runs auction scoring, and returns approval/rejection status.' It distinguishes from sibling tools like list_media_buys and submit_creatives.

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 'when_to_use' section explicitly says when to call ('When an advertiser wants to place a bid') and provides a prerequisite ('Requires inventory_id from list_inventory/get_inventory_item'). It also warns to always confirm with the user because it creates a binding commitment. However, it does not explicitly state when not to use or name alternatives, though the combination hints imply workflow order.

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 non-destructive behavior. The description adds value by disclosing that the tool returns aggregated totals plus a time-series breakdown, which is behavioral context beyond what annotations provide. There is no contradiction with 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 compact and well-structured: a clear one-sentence purpose, a short when-to-use, useful combination hints, and a brief output format. Each section is purposeful and no information is redundant or wasted.

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 lacking an output schema, the description includes an explicit output format ('Totals + time-series breakdown'), which covers the main return-value gap. Combined with usage guidance and annotations, this is a complete and self-sufficient description for a read-only reporting 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?

Input schema covers 100% of parameters with descriptions and enums, including defaults for period and granularity. The description only restates 'Supports period filtering and granularity control' without adding new semantic detail, so it stays at the schema-covered baseline.

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 'Get aggregated performance report for a media buy' and lists specific metrics (spend, impressions, clicks, conversions) with a time-series breakdown. This is a specific verb+resource combination that distinguishes it from sibling tools like get_compliance_status and list_media_buys.

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 <when_to_use> section explicitly says 'To check campaign performance metrics after activation' and mentions period/granularity controls. The <combination_hints> further clarifies the workflow by pairing list_media_buys → get_campaign_report and suggesting get_compliance_status for a full overview, giving 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds valuable behavioral detail by enumerating the specific checks performed: no cookies, no fingerprinting, contextual targeting, data residency, revenue transparency, consent basis, and agent transparency. It also describes the output format, giving a fuller behavioral picture.

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-organized into distinct sections (tool_description, when_to_use, combination_hints, output_format), each concise and purposeful. No filler or redundant content, and the key information 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 only one parameter, clear annotations, a defined output format, and explicit workflow hints, the description fully covers what an agent needs to select and invoke this tool correctly. The combination hints also situate it within the broader campaign lifecycle.

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 sole parameter media_buy_id is already fully described in the schema with 'Media buy UUID to check' and 100% schema coverage. The description does not add further parameter-level detail beyond referencing 'a media buy' context, so the schema carries the semantic burden.

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 'Check nDSG/GDPR/EU AI Act compliance status for a media buy' with a specific verb and resource, and it uniquely distinguishes this tool from sibling tools like get_campaign_report or get_inventory_item. The compliance scope is explicit and actionable.

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 'when_to_use' section explicitly states 'Before activating a campaign or for compliance audits,' and the combination hint 'create_media_buy → get_compliance_status → activate' provides concrete workflow guidance. This clearly communicates when to use this tool versus 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 and idempotentHint=true. The description adds context about the return content (rules, pricing, capacity, active buy count, allowlists/blocklists) and current utilization, which is useful for understanding the tool's 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?

The description is organized into tool_description, when_to_use, combination_hints, and output_format sections. It is concise, though the output_format section slightly repeats the tool_description.

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 simple read tool with one parameter, the description covers what it does, when to use it, and what it returns. The output_format mentions full slot details with rules, pricing, capacity, and active buy count, making it 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?

The input schema has 100% coverage for the single parameter inventory_id, described as 'Inventory slot UUID'. The description does not add additional parameter semantics, but the schema 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 description clearly states the tool's function: 'Get detailed information about a specific publisher inventory slot, including rules and active buy count.' This verb+resource structure distinguishes it from sibling tools like get_product or get_campaign_report.

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 'when_to_use' section explicitly says 'After list_inventory to get full slot details before bidding' and 'Check capacity before create_media_buy', providing clear usage context and sequencing with sibling tools.

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, covering safety. The description adds the alias trait and the output format, but no additional behavioral context like auth needs or error handling. This is adequate given 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 well-structured with clear sections (tool_description, when_to_use, combination_hints, output_format), each concise and without redundancy. It's front-loaded with the core purpose and efficiently conveys all necessary information.

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 simple get-by-ID tool, the description is complete: it defines purpose, usage context, parameter source, output format, and even a combination workflow. The rich annotations and the absence of nested objects further reduce the need for additional explanation.

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 covers 100% of the parameter with type, format, and description. The description adds some context about where to obtain the product UUID (from list_products or nexbid_search), which helps but is not essential since the schema already defines the parameter clearly. 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 "Get detailed product information by ID" with a specific verb and resource. It also notes it's an alias for nexbid_product, which distinguishes it from list_products and nexbid_search, and the output format further clarifies its 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?

The <when_to_use> section explicitly states to use this when you have a product UUID from list_products or nexbid_search. This provides clear context, though it doesn't explicitly mention when not to use it or name alternative get tools. The combination hints additionally suggest a broader workflow, strengthening the 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, so the safety profile is clear. The description adds behavioral context by stating it returns 'available' slots and describing the output content (name, type, floor price, pricing models, capacity, geo targets, status). It also notes filtering by publisher_id, slot_type, pricing_model, or geo, 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 well-structured with clear sections (tool_description, when_to_use, combination_hints, output_format). Every section is relevant and adds value: the tool description is one sentence, when_to_use is two short lines, combination_hints gives workflow, and output_format lists return fields. 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?

With 5 optional params fully documented in the schema, no output schema, and a straightforward list operation, the description provides a complete picture: what it lists, when to use, how it fits into the workflow, and what the response includes. No critical information 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 description coverage is 100% with detailed parameter descriptions (e.g., geo field explains ISO code and matching behavior). The description only repeats 'Filter by publisher_id, slot_type, pricing_model, or geo' without adding new semantic meaning. Per baseline, when schema covers all parameters, a 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 explicitly states 'List available publisher inventory slots for programmatic media buying' with a specific verb and resource. It clearly distinguishes from siblings like get_inventory_item by focusing on listing all slots vs. single-item detail, and names the output (ad slots with pricing, rules, capacity).

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 'when_to_use' section explicitly positions this tool 'Before create_media_buy' and for 'browse publisher ad inventory for campaign planning.' The combination_hints further clarify the flow: list_inventory → get_inventory_item → create_media_buy, and mention filtering options. This is strong contextual 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, openWorldHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat safety. It adds behavioral context by stating the output format (ID, status, bid, budget, spent, dates) and reinforcing it's a view operation. The description aligns with annotations and does not contradict them.

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 compact, with distinct sections for what it does, when to use, combination hints, and output format. Every sentence adds value and the tool description is front-loaded with the core purpose. It avoids redundancy and is well-structured.

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, the description covers purpose, usage filters, related tools, and output format. Since there is no output schema, the explicit output_format section fills that gap. The combination hints provide valuable context for multi-step workflows, making this description 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?

The input schema has 6 parameters, all with descriptions and 100% coverage. The description's mention of filtering by advertiser, publisher, status, or date mirrors the schema but adds no new semantic detail. 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?

The description uses a specific verb+resource ('List media buys') and clarifies it's for viewing campaign history. It distinguishes from sibling mutation tools like create_media_buy and pause by focusing on read-only listing. The purpose is immediately clear.

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 'when_to_use' section explicitly states this is for viewing existing media buys and describes filter dimensions. It also provides combination hints, directing users to get_campaign_report for performance data and get_compliance_status for compliance checks. This gives clear context for when to use this tool versus alternatives, though it doesn't explicitly state exclusions.

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 safety profile is clear. The description adds that this tool delegates to nexbid_search internally, which is useful behavioral context. It also describes the output format (product list fields), going slightly beyond the minimum.

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 split into short, focused sections (tool_description, when_to_use, combination_hints, output_format) with no filler. Every sentence provides value, and the most critical information (what it does and when to use) 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?

Given the tool's simplicity (a read-only alias with six well-documented parameters and no output schema), the description is complete. It includes purpose, usage guidance, combination hints, and even specifies the output format fields, leaving no obvious gaps for an AI agent to infer.

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 fully documents all six parameters. The description adds no extra parameter-specific meaning, but it does hint at the query semantics via 'product query' and output fields. Baseline of 3 is appropriate since schema carries the burden.

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 'Search for products in the Nexbid marketplace' with a clear verb and resource, and explicitly identifies itself as an alias for nexbid_search with content_type='product'. This distinguishes it from sibling tools like nexbid_search and get_product.

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 'when_to_use' section explicitly states when to use this tool ('When an agent needs to discover products') and what not to use it for ('not recipes or services'). It also provides an alternative by saying to use nexbid_search with content_type filter for those cases, satisfying the when/when-not/alternatives requirement.

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 the tool safe (readOnlyHint, idempotentHint, non-destructive). The description adds behavioral context beyond annotations by specifying that results include 'product counts' and that output can be 'optionally filtered by country,' which are not evident from annotations or the schema alone.

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 distinct sections (tool_description, when_to_use, combination_hints, output_format). Each sentence adds value: the combination hint with nexbid_search is especially useful. It is compact without unnecessary verbosity, though the XML-style tags add slight overhead.

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 simple read-only list tool with one optional parameter and no output schema, the description is complete. It explains what the tool returns ('list of categories with product counts'), the optional country filter, and when to use it relative to nexbid_search. No critical information appears 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% (the geo parameter has a full description). The description does not add much beyond the schema—only says 'Optionally filter by country,' which mirrors the schema. Since the schema already documents the parameter thoroughly, a 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: 'List all available product categories in the Nexbid marketplace with product counts.' It identifies the resource (categories), the action (list), and the scope (Nexbid marketplace), and distinguishes it from sibling tools like nexbid_search by positioning it as a pre-search exploration step.

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 guidance is provided: 'When user wants to explore what is available before searching. Use BEFORE nexbid_search to help narrow down the query.' This directly states when to use it and names the alternative tool, giving clear context 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 readOnlyHint and idempotentHint, so the safety profile is known. The description adds useful behavioral details: it mentions the purchase intent was created via nexbid_purchase, and specifies output as current status (pending/completed/expired) and checkout link if active. 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 structured into clear sections with minimal content. Every phrase earns its place: tool purpose, usage timing, prerequisite, and output format. No redundancy or verbose language.

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 simple single-parameter tool with no output schema, the description covers all essential context: when to use, prerequisite (intent_id from nexbid_purchase), and expected output format. The combination hint adds workflow context. Complete for the tool's complexity.

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 parameter intent_id is already well-documented as a purchase intent UUID from nexbid_purchase. The description repeats this same information in <when_to_use>, adding marginal value 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 checks the status of a purchase intent created via nexbid_purchase. It specifies the exact resource (purchase intent) and action (check status), distinguishing it from sibling tools like cancel, settle, or nexbid_purchase itself.

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 <when_to_use> section explicitly states this tool should be used after nexbid_purchase when the user wants the order status. The combination hints reinforce that it always follows nexbid_purchase and no other tool is needed, providing 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, idempotentHint, and destructiveHint=false, establishing a safe, non-mutating operation. The description adds useful behavioral context by enumerating the returned information (price, availability, description, purchase link) and noting it is 'full product details.' No contradictions 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?

The description is organized into short, purposeful sections (description, when_to_use, combination_hints, output_format). Every sentence adds value; there is no redundancy or 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?

For a simple read-only tool with one required parameter and three well-documented parameters, the description fully covers purpose, usage, output format, and workflow context. Even without an output schema, the output_format section lists the expected fields. Rich annotations and combination hints complete the picture.

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. The description adds meaning beyond the schema by explaining that product_id comes from a previous nexbid_search result, which clarifies the parameter's origin and intended 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 clearly states the tool's action: 'Get detailed product information by ID from the Nexbid marketplace.' It specifies the resource (Nexbid product), scope (by ID), and explicitly distinguishes itself from browsing via nexbid_search and purchasing via nexbid_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?

Provides explicit when-to-use: 'When you have a specific product UUID from a previous nexbid_search result.' Also gives a clear exclusion: 'Do NOT use for browsing — use nexbid_search instead.' Addition of combination hints reinforces workflow (search → product → purchase).

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 discloses that the tool initiates rather than completes a purchase, mandates presenting the checkout link for user confirmation, and differentiates output behavior by mode (prefill_link vs wallet_pay). It adds meaningful context (wallet requirement, intent ID/status) beyond the basic readOnlyHint=false annotation, 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 description is front-loaded with the core purpose in two sentences, then organized into compact, high-value sections (when_to_use, combination_hints, output_format). Every sentence contributes essential guidance; there is no fluff or repetition of 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?

Despite the absence of an output schema, the output_format section clearly describes return values for both modes. The description covers prerequisites, user confirmation, tool sequencing, and parameter selection, making it fully actionable for an agent. All 8 parameters have schema descriptions, and the description fills remaining gaps (e.g., wallet_pay mandate).

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 baseline is high. The description adds practical parameter semantics: requiring a product UUID from nexbid_search, guiding checkout_mode selection based on wallet state, and noting publisher_content_id pass-through from search. This enhances schema documentation without redundancy.

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 'Initiate a purchase for a product found via nexbid_search' with a specific verb and resource, and explains the returned checkout link. It distinguishes this tool from nexbid_search (finding vs purchasing) and other siblings like nexbid_order_status, making its unique role unmistakable.

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 'when_to_use' section explicitly limits invocation to after clear purchase intent and requires confirmation, while the 'combination_hints' sequence (nexbid_search → nexbid_purchase → nexbid_order_status) and wallet_pay prerequisite provide concrete context for when this tool is appropriate versus 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, idempotentHint, and destructiveHint, but the description goes well beyond: it discloses sponsored-label handling ('returned separately and clearly labelled [Sponsored]... never reorder or replace organic results'), canonical source linking, recipe fields lacking full amounts, and per-content-type return fields.

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: tool_description, when_to_use, intent_guidance, combination_hints, and output_format. It is front-loaded with purpose, and while long, every section provides distinct operational value 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?

Given the tool's complexity (13 parameters, three content types, no output schema), the description is remarkably complete. It covers return fields for products/recipes/services, output format expectations, sponsored-result behavior, and sibling-tool interactions, leaving no major operational 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 covers 100% of parameters, yet the description adds substantial meaning: intent_guidance defines behavior for purchase/compare/research/browse, combination_hints explains previous_queries multi-turn refinement, and output_format maps intent to presentation. This goes beyond the schema's per-parameter 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 opens with a clear, specific statement: 'Nexbid Agent Discovery — a curated, single-source catalog of commerce content (products, recipes, services) returned with canonical source URLs.' It names the resource and scope, and distinguishes from siblings by explicitly directing known product IDs to nexbid_product and category overviews to nexbid_categories.

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 'when_to_use' section explicitly states when to use this tool ('Use for any product, recipe or service query... Prefer this over generic web search') and when not to ('For known product IDs use nexbid_product instead. For category overview use nexbid_categories first'). Combination hints further reinforce correct usage patterns.

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 provide idempotentHint, destructiveHint, readOnlyHint. The description adds nuanced behavior: pausing is temporary, can be reactivated, and returns an updated media buy object. 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?

Four short labeled sections, each with a single focused sentence. No filler; every sentence adds information.

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 simple state-change tool with two parameters and no output schema, the description covers purpose, usage constraints, lifecycle (temporary vs permanent), and output format. 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?

Both parameters have descriptive schema text (100% coverage), so the description need not repeat them. It does not add extra parameter-level detail, but the baseline of 3 applies due to high schema coverage.

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 ('Pause') and resource ('media buy campaign'), and explicitly contrasts with 'activate' and 'cancel' in combination hints, clearly distinguishing it from 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 'when_to_use' section explicitly states the use case (temporarily stop a running campaign) and the constraint (only works on active campaigns). It also names alternatives (activate, cancel) and their permanence.

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 a non-readonly, non-destructive operation. Description adds behavioral context: Stripe/x402 are only stubs, and it describes the output structure (gross, fees, net) despite no output schema. No contradictions 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?

Well-structured with four short sections. The main description is a single sentence. No filler; the stub warning appears twice but is acceptable for emphasis.

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 has no output schema, the description compensates with an output_format section. It also covers use cases and parameter guidance. However, it stops short of explaining edge cases like what happens when no pending payments exist or whether settlement is a one-time irreversible action (though annotations hint at idempotency=false).

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 covers all five parameters with descriptions (100% coverage). Description adds value by explicitly stating method='manual' works for CSV and Stripe/x402 are stubs, clarifying the enum semantics. Combination hints reinforce filter usage but don't add syntax 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 immediately states 'Settle pending payments for media buys,' which uses a specific verb and resource. It further differentiates from sibling tools by listing settlement methods, clearly positioning it as post-campaign revenue collection rather than creation or reporting.

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 ('publisher wants to collect earned revenue' / 'advertiser needs to settle outstanding charges') and method-specific guidance ('Use method='manual' for CSV export'). It also warns that Stripe and x402 are stubs, effectively telling the agent not to use them yet. Suggests a combination with get_campaign_report.

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=false and idempotentHint=true, so mutation and idempotency are covered. The description adds workflow context ('Required before activation') and output format ('Updated media buy with creative info attached'). It does not contradict annotations, though it omits failure modes or permission details—acceptable given the annotation 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?

The description is well-structured with clear sections (tool_description, when_to_use, combination_hints, output_format). It is front-loaded with the core action and every sentence earns its place, providing workflow, creative types, and output 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 tool with a nested object and no output schema, the description provides a complete workflow, output expectations, and creative type examples. The only minor gap is not specifying whether creative_ref and creative_data are mutually exclusive or complementary, but overall the description is robust for an agent to select and invoke the 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 description coverage is 100%, so all parameters are documented. The description adds example creative types ('banner, native, snippet, video, text') and output expectations, but doesn't clarify the relationship or usage of creative_ref vs creative_data. This is marginal value beyond the schema, so a 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 'Submit or update creative assets for an existing media buy' with a specific verb and resource. It also differentiates from siblings by noting it is 'Required before activation,' which distinguishes it from create_media_buy and activate.

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 provides when-to-use guidance: 'After create_media_buy returns approved status. Upload creative before activating.' It also gives a workflow sequence 'create_media_buy (approved) → submit_creatives → activate' and lists accepted creative types, making usage context very clear.

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 discloses key behavioral side effects: billing the advertiser, creating a ledger entry, and decrementing the media buy budget. It also specifies the output format (Event ID, charged amount, etc.). These go beyond the annotation flags (readOnlyHint=false, destructiveHint=false) and provide useful context about the financial impact. However, it could be more explicit about irreversibility or idempotency, though the annotations partially cover this.

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: tool_description, when_to_use, combination_hints, and output_format. Each section is concise and directly useful, with no redundant or filler content. The main purpose is front-loaded in the first sentence, making it easy for an agent to quickly grasp the tool's function.

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 tool has 6 parameters, nested objects, and no output schema, so the description needs to cover return values and usage context. It does this by providing an output format (Event ID, charged amount, etc.) and workflow hints. It also mentions the ledger entry and budget decrement side effects. However, it does not explain what happens if `brand_content_id` is omitted or edge cases like partial data delivery, which could be useful but are not critical given the schema coverage.

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 descriptions cover 100% of the parameters, so the baseline is 3. The description adds value by explaining how `snippet_type` maps to billing tiers (basic: 10¢, etc.), which clarifies the semantic meaning of that parameter beyond its enum values. It also hints at the purpose of `brand_content_id` (for analytics) indirectly through the billing context, though the schema already describes that. Overall, it enhances parameter understanding.

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: 'Track delivery of an enriched snippet and bill the advertiser. Creates a ledger entry and decrements the media buy budget.' This uses a specific verb (track/bill) and resource (enriched snippet, media buy), distinguishing it from siblings like activate or get_campaign_report which serve different purposes.

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 `when_to_use` section explicitly states when to use the tool ('When an agent delivers enriched content from a media buy') and provides tier-based billing details. The `combination_hints` further clarify workflow with activate and get_campaign_report. However, it does not explicitly state when NOT to use it or name alternative tools for related scenarios, so it misses the full 'when-not/alternatives' criteria.

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