discovery

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

Annotations cover readOnlyHint=false, destructiveHint=false, etc., but the description adds valuable context: it requires 'creative to be submitted first' (a prerequisite), mentions the output format ('Activated media buy with won_at timestamp'), and hints at idempotency through combination flows. It does not contradict annotations and enhances understanding of operational constraints.

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>, etc.), each sentence is purposeful with zero waste, and it's front-loaded with the core action. It efficiently conveys necessary information without 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 complexity (a mutation with prerequisites), rich annotations, and no output schema, the description is complete: it explains the purpose, usage context, prerequisites, output format, and relationships with sibling tools, covering all essential aspects for an AI agent to use it correctly.

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

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

Schema description coverage is 100%, with the parameter 'media_buy_id' fully documented in the schema. The description does not add extra semantic details about the parameter beyond implying it's for an 'approved media buy', so it meets the baseline of 3 where the schema handles 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 explicitly states the verb 'activate' and the resource 'approved media buy' with the specific purpose 'to start serving'. It distinguishes from siblings like 'pause', 'cancel', and 'submit_creatives' by focusing on initiating service after approval and creative submission.

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 guidance: use 'after submit_creatives, when ready to go live with the campaign'. It also mentions alternatives for later actions ('paused later with pause, or cancelled with cancel') and combination hints for enriched snippet buys ('submit_creatives → activate → track_enriched_snippet').

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 provide readOnlyHint=false, destructiveHint=false, idempotentHint=true, and openWorldHint=true. The description adds valuable behavioral context beyond annotations: it discloses that cancellation is 'terminal — cannot be reactivated', 'Cannot be undone', and 'Remaining budget is released'. These are critical behavioral traits not covered by annotations. No contradiction with annotations exists.

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 with clear sections (<tool_description>, <when_to_use>, <combination_hints>, <output_format>), each containing only essential information. Every sentence earns its place by providing distinct guidance without 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 complexity (destructive terminal operation), rich annotations, and 100% schema coverage, the description provides complete contextual information. It covers purpose, usage guidelines, behavioral implications, and output format, compensating for the lack of output schema by specifying 'Updated media buy with cancelled status'.

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

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

Schema description coverage is 100%, with both parameters ('media_buy_id' and 'reason') well-documented in the schema. The description doesn't add any parameter-specific semantics beyond what the schema provides, so it meets the baseline of 3 for high schema coverage without extra 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 specific action ('Cancel a media buy campaign') and resource ('media buy campaign'), distinguishing it from sibling tools like 'pause' by emphasizing it's a terminal state. The title 'Cancel Campaign' in annotations reinforces this, but the description adds the critical distinction from temporary suspension.

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 advertiser wants to permanently stop a campaign') and when not to ('Use pause for temporary stops'), with clear alternatives named. The <combination_hints> reinforces this guidance by contrasting with '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?

Annotations already indicate non-read-only and non-destructive. The description adds context: validates rules, runs auction scoring, returns approval/rejection, and mentions binding commitment. 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?

The description is well-structured into logical sections (tool_description, when_to_use, combination_hints, output_format) with no superfluous information. Every sentence serves a 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?

Given 16 parameters and no output schema, the description provides output format (media buy ID, status, auction score, rejection reason) and workflow hints. Could mention error conditions or more details on validation, but still solid.

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%, but the description adds value beyond schema: explains that inventory_id comes from list_inventory, describes score formula, and documents fallback behavior for pacing and frequency cap cascade.

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 'Create a media buy (bid on publisher inventory)' with a specific verb and resource. It distinguishes from sibling tools like list_media_buys and activate by detailing the auction process and output.

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 prerequisites (requires inventory_id from list_inventory/get_inventory_item) and warns to confirm with user before calling due to binding commitment. <combination_hints> provides a typical workflow and alternative handling for rejection.

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 safety hints (readOnlyHint: true, destructiveHint: false), but the description adds valuable context beyond this: it specifies the tool provides aggregated reports with time-series breakdown, and hints at period filtering and granularity control. It doesn't contradict annotations, but could mention more about rate limits or data freshness.

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>, etc.), front-loaded with the core purpose, and every sentence adds value without redundancy. It's appropriately sized for the tool's complexity.

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, rich annotations covering safety, and no output schema, the description is complete: it explains the purpose, usage, combinations, and output format. It compensates for the lack of output schema by detailing what the tool returns (totals + time-series breakdown).

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 parameters well. The description adds some context by mentioning 'period filtering and granularity control', which aligns with the 'period' and 'granularity' parameters, but doesn't provide additional semantic details beyond what's in the schema. This meets the baseline for 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 clearly states the tool's purpose with specific verbs ('Get aggregated performance report') and resources ('for a media buy'), listing the exact metrics provided (spend, impressions, clicks, conversions). It distinguishes from siblings like 'list_media_buys' by focusing on performance analysis rather than listing.

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 it ('To check campaign performance metrics after activation') and provides combination hints that guide usage relative to alternatives (e.g., 'list_media_buys → get_campaign_report for performance analysis', 'Pair with get_compliance_status for full campaign overview'). This clearly differentiates it from other 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?

While annotations already indicate this is a read-only, non-destructive, idempotent operation, the description adds valuable context about what specific compliance checks are performed (no cookies, fingerprinting, contextual targeting, etc.) and mentions use for regulatory reporting and audit trails, which goes beyond the structured 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 containing focused, essential information without redundancy. Every sentence serves a clear purpose in helping the agent understand and use the tool effectively.

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, comprehensive annotations, and lack of output schema, the description provides strong context about what compliance checks are performed, when to use the tool, workflow positioning, and expected output format. The main gap is the absence of a formal output schema, but the description compensates well with output format details.

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, the schema already fully documents the single required parameter. The description doesn't add any additional parameter semantics beyond what's in the schema, 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 purpose with specific verbs ('Check', 'Verifies') and resources ('compliance status for a media buy'), distinguishing it from siblings by focusing on regulatory compliance verification rather than campaign management or reporting functions.

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 guidance on when to use the tool ('Before activating a campaign or for compliance audits'), includes combination hints showing its place in workflows, and distinguishes it from alternatives by focusing specifically on compliance verification rather than general campaign operations.

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 readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds valuable context beyond this: it specifies that the tool shows 'brand/category allowlists, blocklists, and current utilization', which are behavioral traits not covered by annotations. No contradiction with annotations exists.

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 containing concise, front-loaded sentences. Every sentence adds value without redundancy, making it efficient and easy to parse.

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 (read-only, single parameter) and rich annotations (readOnlyHint, openWorldHint, etc.), the description is complete. It covers purpose, usage guidelines, combination hints, and output format, compensating for the lack of an output schema by detailing what information is returned. No gaps are evident for this type of 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%, with the inventory_id parameter fully documented in the schema as 'Inventory slot UUID'. The description does not add any further meaning or details about the parameter beyond what the schema provides, so it meets the baseline of 3 where the 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 verb 'Get' and resource 'detailed information about a specific publisher inventory slot', specifying it includes 'rules and active buy count'. It distinguishes from siblings like list_inventory (which lists items) and create_media_buy (which creates buys), making the purpose specific and differentiated.

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 list_inventory to get full slot details before bidding' and 'Check capacity before create_media_buy', providing clear context and alternatives. The combination_hints further reinforce the workflow with list_inventory → get_inventory_item → create_media_buy, offering explicit guidance on when to use this tool versus others.

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 annotations already provide strong behavioral hints (readOnlyHint: true, idempotentHint: true, etc.), so the bar is lower. The description adds valuable context by specifying the output format details (name, description, price, etc.) and workflow combinations, which goes beyond what annotations alone convey. No contradictions with annotations are present.

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>, etc.), each sentence is purposeful, and there is no redundant information. It efficiently conveys necessary details without waste, making it easy for an agent to parse and understand.

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 (1 parameter, 100% schema coverage), rich annotations, and no output schema, the description is complete. It covers purpose, usage guidelines, output format, and workflow hints, providing all needed context for an agent to correctly invoke the tool 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 description coverage is 100%, with the parameter 'product_id' fully documented in the schema as a UUID. The description adds minimal semantic value beyond this, as it only reiterates 'by ID' without providing additional context like format examples or edge cases. This meets the baseline for 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 clearly states the tool's purpose with a specific verb ('Get detailed product information') and resource ('by ID'), and explicitly distinguishes it from its sibling 'nexbid_product' by calling it an alias. This provides precise differentiation from similar tools in the sibling list.

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

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

The description includes explicit guidance in the <when_to_use> section, specifying when to use this tool ('When you have a product UUID from list_products or nexbid_search') and implicitly when not to use it (e.g., when you don't have a UUID). The <combination_hints> section further clarifies workflow alternatives, 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?

Annotations already cover key behavioral traits (readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true), so the bar is lower. The description adds valuable context beyond annotations by specifying the tool's role in a workflow ('list_inventory → get_inventory_item for slot details → create_media_buy to bid') and hinting at filtering capabilities, though it doesn't detail rate limits or auth needs. No contradiction with annotations exists.

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 containing focused, front-loaded information. Every sentence earns its place by adding value, such as workflow guidance or output details, with no wasted words 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 moderate complexity (5 parameters, no output schema), the description is complete. It covers purpose, usage guidelines, behavioral context (via annotations and added hints), and output format details, compensating for the lack of an output schema. The annotations provide safety and idempotency info, making this description fully adequate for agent use.

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 5 parameters. The description adds minimal parameter semantics beyond the schema, only mentioning in <combination_hints> to 'Filter by publisher_id, slot_type, or pricing_model for targeted results,' which doesn't provide new syntax or format details. This meets the baseline of 3 when the 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's purpose with specific verbs ('List available publisher inventory slots') and resources ('ad slots with pricing, rules, and capacity info'). It distinguishes itself from siblings like 'get_inventory_item' (which provides slot details) and 'create_media_buy' (which bids on slots), making the scope and differentiation explicit.

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

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

The description includes explicit guidance in the <when_to_use> and <combination_hints> sections, stating to use it 'Before create_media_buy — discover which slots are available' and 'Use to browse publisher ad inventory for campaign planning.' It also provides alternatives like filtering by parameters and references sibling tools ('get_inventory_item for slot details'), giving clear context for when and how to use this 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 provide readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true. The description adds valuable context beyond annotations by specifying it's for viewing existing campaigns and listing specific output fields (ID, status, bid, budget, spent, dates). However, it doesn't mention rate limits, authentication requirements, or pagination 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 efficiently structured with clear XML-like sections (<tool_description>, <when_to_use>, <combination_hints>, <output_format>), each containing only essential information. Every sentence earns its place, with no redundant or unnecessary 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?

Given the tool's complexity (list operation with 6 optional filters), rich annotations (4 hints), and 100% schema coverage, the description provides complete context. The output format section compensates for the lack of output schema by specifying what fields are returned. The combination hints provide excellent guidance about related tools.

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 all 6 parameters well-documented in the schema. The description mentions filtering by advertiser, publisher, status, or date, which aligns with the schema but doesn't add significant semantic value beyond what's already in the parameter descriptions. The baseline of 3 is appropriate when the 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's purpose with specific verbs ('list media buys') and resources ('media buys'), and distinguishes it from siblings by specifying it's for viewing existing campaigns rather than creating or modifying them. The <tool_description> section explicitly says 'List media buys with optional filters' and 'View campaign history for advertisers or publishers.'

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 view existing media buys (campaigns)' and lists specific filter criteria. The <combination_hints> section provides clear alternatives by naming two sibling tools (get_campaign_report, get_compliance_status) and specifying when to use them instead (for performance data or compliance checks).

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 readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=true, covering safety and idempotency. The description adds useful context beyond this: it discloses that this is an alias that delegates to nexbid_search internally, which helps the agent understand implementation behavior. However, it doesn't mention rate limits or authentication needs, leaving some behavioral aspects uncovered.

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 containing only essential information. Every sentence earns its place by providing distinct value, such as clarifying the alias relationship, usage context, workflow hints, and output format.

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 (search with 6 parameters), rich annotations (covering safety and idempotency), and 100% schema coverage, the description is complete. It adds necessary context like the alias relationship, sibling differentiation, usage guidelines, combination hints, and output format, compensating for the lack of an output schema. No critical gaps remain for agent understanding.

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 fully documents all 6 parameters. The description doesn't add any parameter-specific information beyond what's in the schema (e.g., it doesn't explain how 'query' interacts with 'category' or 'brand'). With high schema coverage, the baseline is 3, and the description doesn't compensate with additional param semantics.

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 'Search for products in the Nexbid marketplace' with a specific verb ('search') and resource ('products'), and distinguishes it from siblings by noting it's an alias for nexbid_search with content_type='product'. This clearly differentiates it from tools like list_inventory or 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 description provides explicit guidance in the <when_to_use> section: 'When an agent needs to discover products (not recipes or services)' and 'For recipes/services use nexbid_search with content_type filter.' It also mentions it's a 'convenience alias' that delegates internally, clarifying when to use this vs. the underlying nexbid_search 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 declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral context by specifying that results include 'product counts' (specific data characteristics) and confirming the optional filtering capability. It does not mention rate limits or pagination behavior, but effectively complements the safety annotations with data structure expectations.

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

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

The description uses well-structured sections (tool_description, when_to_use, combination_hints, output_format) with zero wasted words. Each sentence earns its place: purpose is front-loaded, workflow guidance is explicit, and output expectations are set efficiently. The XML-like structure enhances scannability.

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 (1 optional string parameter, no nested objects) and rich annotations (4 hint fields), the description is complete. It compensates for the missing output_schema by including an <output_format> section describing the list structure. The workflow guidance (when to use vs nexbid_search) provides sufficient orchestration context for an AI agent.

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 (the 'geo' parameter is fully documented as 'ISO 3166-1 alpha-2 country code'), the baseline score applies. The description mentions 'Optionally filter by country' which aligns with the schema but does not add additional semantic details, examples, or validation guidance beyond what the schema provides.

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 the tool 'List[s] all available product categories in the Nexbid marketplace with product counts' and specifies the optional country filter. It clearly distinguishes from sibling nexbid_search by positioning this as a browse/exploration tool rather than a search 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 <when_to_use> section explicitly states to use this 'BEFORE nexbid_search to help narrow down the query' and identifies the specific user intent ('explore what is available'). The <combination_hints> further reinforces the workflow sequence (categories → search with filter), providing clear alternatives and sequencing 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 cover safety profile (readOnly, idempotent). Description adds workflow context (follows purchase creation) and discloses output values ('pending/completed/expired') and conditional fields ('checkout link if still active') not present in structured data.

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?

Uses structured XML-like tags to organize distinct sections (tool_description, when_to_use, combination_hints, output_format). Content is front-loaded and dense, though the tag syntax adds slight verbosity.

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 status check tool, description adequately covers purpose, prerequisites, sequencing, sibling relationships, and output format (enumerating status states and conditional checkout link) despite absence of formal 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 has 100% coverage describing intent_id as 'Purchase intent UUID'. Description adds semantic origin context ('from nexbid_purchase', 'returned by nexbid_purchase'), helping the agent understand data flow from the sibling tool.

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

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

Description uses specific verb 'Check' with resource 'status of a purchase intent', and explicitly scopes it to intents 'created via nexbid_purchase', clearly distinguishing it from sibling tools like nexbid_purchase (creation) and nexbid_search (discovery).

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?

<when_to_use> explicitly states the temporal dependency ('After nexbid_purchase was called') and prerequisite ('Requires the intent_id UUID'). <combination_hints> provides clear sequencing guidance ('Always follows nexbid_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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, signaling a safe read operation. The description adds behavioral context by listing output fields (e.g., purchase link) and combination hints, which informs the agent about typical usage flow without contradicting 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 highly structured with clear sections (<tool_description>, <when_to_use>, <combination_hints>, <output_format>). Every sentence serves a purpose, and the total length is appropriate for the tool's simplicity. 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 tool's 3 parameters (100% schema coverage) and rich annotations, the description compensates for the lack of an output schema by detailing return fields. It also provides usage and combination context. The description could mention error handling or rate limits, but overall it is sufficiently complete for an agent to invoke 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 has 100% described parameters, so the schema already documents agent_id, product_id (UUID), and session_id. The description adds limited extra semantics: it mentions product UUID context (from search) but does not provide new details 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 tool description clearly states it retrieves detailed product information by ID from the Nexbid marketplace, specifying return fields like price, availability, description, and purchase link. While it distinguishes from sibling 'nexbid_search' (browsing), it does not explicitly differentiate from the sibling 'get_product' which may also retrieve product 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?

A dedicated <when_to_use> section explicitly states the tool should be used when a UUID is available from a previous nexbid_search result, and warns not to use for browsing—directing to nexbid_search instead. Additionally, <combination_hints> provide clear orchestration steps: call after nexbid_search and before nexbid_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?

Description discloses that the tool does not complete the purchase but returns a checkout link, that wallet_pay requires an active mandate, and that the agent should confirm with the user. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with initiating a purchase (non-destructive but not read-only). 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?

Organized into clear, short sections: tool_description, when_to_use, combination_hints, output_format. Each sentence serves a purpose, no 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 8 parameters, 0 required, and no output schema, the description provides adequate context: output format for both checkout modes, prerequisites, and usage hints. It ensures the agent can select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline 3. The description adds value through combination_hints (e.g., checkout_mode=wallet_pay when user has connected wallet) and output_format explaining return values for different modes, exceeding schema details.

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 initiates a purchase for a product from nexbid_search, returns a checkout link, and instructs the agent to present it for confirmation. This distinguishes it from sibling tools like nexbid_search and nexbid_order_status.

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: only after clear purchase intent, requires product UUID from nexbid_search/nexbid_product, and always confirm with user. It also references nexbid_order_status for post-purchase, showing awareness of 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 significant behavioral context beyond annotations: it explains ranked results, intent-specific output formatting, multi-turn refinement via previous_queries, and that recipe results include targeting signals for ad matching. No contradictions with annotations (readOnlyHint, idempotentHint).

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 (description, when_to_use, intent_guidance, combination_hints, output_format). Every section adds necessary information without redundancy. It is front-loaded with the main 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?

Given the tool's complexity (13 parameters, no output schema), the description is remarkably complete. It covers return values for each content type, intent-specific output, combination hints, and multi-turn refinement. Without an output schema, it adequately describes what the tool returns.

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%, but the description adds substantial value: <intent_guidance> explains behavior per intent, content_type filter is elaborated, and previous_queries has an example. This goes well beyond the schema's 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 clearly states it searches and discovers products, recipes, and services in the Nexbid marketplace. It distinguishes itself from sibling tools like nexbid_product (for known IDs) and nexbid_categories (for category overview), making the purpose 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?

The <when_to_use> section explicitly states it is the primary discovery tool for any product, recipe, or service query, and provides clear alternatives for known product IDs (use nexbid_product) and category overview (use nexbid_categories first). This provides excellent usage guidance.

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

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

The description adds valuable behavioral context beyond annotations: it specifies that pausing is temporary vs. permanent cancellation, indicates reactivation is possible with the 'activate' tool, and clarifies it only works on active campaigns. While annotations cover idempotency and non-destructive nature, the description provides practical workflow context that helps the agent understand the tool's role in campaign lifecycle management.

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 XML-like sections (<tool_description>, <when_to_use>, <combination_hints>, <output_format>), each containing precisely one sentence of essential information. There's no redundancy or wasted words, and the most critical information (purpose) appears first.

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 (state change operation), rich annotations, and complete schema coverage, the description provides excellent contextual completeness. It covers purpose, usage guidelines, behavioral context, and output format, creating a comprehensive understanding despite the absence of an output schema.

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

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

With 100% schema description coverage, the schema already documents both parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.

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 specific action ('Pause an active media buy campaign') and resource ('media buy campaign'), distinguishing it from siblings like 'cancel' (permanent) and 'activate' (reactivation). It explicitly mentions the temporary nature and reactivation capability.

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 guidance in the <when_to_use> section: 'When an advertiser wants to temporarily stop a running campaign' and 'Only works on active campaigns.' The <combination_hints> section further clarifies alternatives: 'activate → pause (temporary) or cancel (permanent)' and 'Paused campaigns can be reactivated with activate.'

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 valuable behavioral context beyond what annotations provide. While annotations indicate this is a non-readonly, non-destructive, non-idempotent operation with open-world data, the description reveals implementation details about Phase 2 stubs for Stripe and x402 methods, specifies that manual method produces CSV exports, and mentions filtering capabilities by media_buy_id, publisher_id, or period. This provides practical implementation context that annotations don't cover.

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 perfectly structured with clear sections (<tool_description>, <when_to_use>, <combination_hints>, <output_format>) that make information easy to find. Every sentence earns its place by providing essential guidance, and the content is front-loaded with the core purpose. There's zero wasted text 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 complexity (payment settlement with multiple methods), the description provides complete context despite having no output schema. It covers purpose, usage scenarios, method-specific behaviors, parameter filtering strategies, combination with other tools, and output format details. The annotations provide safety context, and the description fills in all remaining gaps about how the tool actually behaves in practice.

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, the baseline would be 3, but the description adds meaningful context about parameter usage. It explains that 'manual' method is for CSV export while other methods are Phase 2 stubs, and provides filtering guidance ('Filter by media_buy_id, publisher_id, or period') that helps understand how parameters work together. This adds semantic value beyond the schema's technical 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 the tool's purpose with specific verbs ('settle pending payments for media buys') and distinguishes it from siblings by focusing on payment settlement rather than campaign management, inventory listing, or other operations. It identifies the exact resource being acted upon (pending payments) and the action (settling).

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 guidance on when to use the tool ('When a publisher wants to collect earned revenue or an advertiser needs to settle outstanding charges'), when not to use certain methods ('Stripe and x402 are stubs (Phase 2)'), and alternatives for different scenarios ('Use method='manual' for CSV export'). It also includes combination hints that show sequencing with other tools ('get_campaign_report → settle').

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 valuable behavioral context beyond annotations: it specifies this is 'required before activation' (a workflow constraint) and lists creative types (banner, native, etc.) that help understand what can be submitted. Annotations already cover idempotency, non-destructive nature, and open-world status, so the description appropriately supplements rather than contradicts 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 efficiently structured with clear sections (<tool_description>, <when_to_use>, etc.), each containing only essential information. Every sentence serves a distinct purpose without redundancy, and the information is front-loaded with the core purpose stated first.

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 mutation tool with rich annotations (idempotent, open-world) but no output schema, the description provides good context: it explains the workflow position, prerequisites, creative types, and output format. However, it doesn't detail error conditions or specific permission requirements, leaving some gaps in completeness.

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, the schema already documents all 4 parameters thoroughly. The description doesn't add significant parameter semantics beyond what's in the schema, though it does imply creative_type values through the creative types list. This meets the baseline expectation when schema coverage is complete.

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 ('submit or update creative assets') and identifies the target resource ('for an existing media buy'). It distinguishes from siblings like 'create_media_buy' by specifying it works on existing buys, and from 'activate' by indicating it's required before activation.

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 guidance on when to use this tool: 'After create_media_buy returns approved status' and 'Upload creative before activating.' It also names the alternative tool 'activate' in the combination hints, clearly positioning this as a prerequisite step in the workflow.

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 creates a ledger entry and decrements the media buy budget, which is consistent with the annotations (readOnlyHint=false, destructiveHint=false). It also provides an output format showing what the tool returns. This adds 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?

The description is well-structured with clear sections (tool_description, when_to_use, combination_hints, output_format). It is concise and front-loaded with the core purpose. No unnecessary 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?

Given the tool has 6 parameters with full schema coverage and no output schema, the description compensates by listing the output format and providing workflow context via combination_hints. It lacks error handling or budget insufficiency info, but overall sufficient for a tracking tool.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds pricing info for snippet_type values, but the enum descriptions in the schema already list the tiers. Marginal added 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 tracks delivery of an enriched snippet and bills the advertiser, which is a specific verb-resource pair. The combination_hints distinguish it from siblings like activate by showing the workflow sequence.

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: after delivering enriched content from a media buy. It also provides pricing tiers for the snippets. While it doesn't list when not to use, the context from combination_hints clarifies it's a specific step in a workflow.

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