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 this is a non-readOnly, non-destructive, non-idempotent operation. The description adds valuable behavioral context beyond annotations: it discloses the binding commitment nature, validation rules, auction scoring process, and approval/rejection outcomes. However, it doesn't mention rate limits or authentication requirements.

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 essential information with zero waste. Every sentence serves a specific purpose in guiding tool usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a media buy creation tool with 13 parameters and no output schema, the description provides comprehensive context: purpose, usage guidelines, workflow integration, behavioral details (binding commitment, auction mechanics), and output format. It compensates well for the lack of output schema and annotations limitations.

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 in the schema. The description adds some context about parameter usage in the combination hints (e.g., 'adjust bid/brand/category' for rejection handling) and the score formula references quality and context parameters, but doesn't provide significant additional semantic meaning beyond what's in the schema.

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

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

The description clearly states the specific action ('Create a media buy'), the resource ('bid on publisher inventory'), and distinguishes it from siblings by specifying it's for creating bids rather than listing, getting, or managing existing buys. It provides detailed context about auction mechanics (AdCP-compatible first-price sealed-bid) that sets it apart.

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

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

Explicit guidance is provided in dedicated sections: 'When an advertiser wants to place a bid on a publisher inventory slot' specifies the use case, 'Requires inventory_id from list_inventory/get_inventory_item' states prerequisites, 'ALWAYS confirm with user before calling — creates a binding commitment' gives critical warnings, and combination hints show workflow 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 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 declare readOnlyHint=true and destructiveHint=false. The description adds valuable behavioral context by detailing the return payload (name, description, price, currency, availability, brand, category, purchase link) in the output_format section, which compensates for the lack of output schema. Does not mention error behaviors (e.g., invalid UUID), preventing a 5.

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 sections (tool_description, when_to_use, combination_hints, output_format) that front-load critical information. Every sentence serves a distinct purpose; no filler content. The format efficiently separates what the tool does from when to use it and what it returns.

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 lookup tool, the description is comprehensive. It compensates for the missing output schema by explicitly listing all returned fields. Covers sibling relationships (nexbid_search, nexbid_purchase), usage constraints, and return values adequately for agent decision-making.

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

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

Schema coverage is 100% (product_id described as 'Product UUID'), establishing a baseline of 3. The description adds workflow context that the ID should come 'from a previous nexbid_search result,' helping the agent understand the parameter's semantic origin beyond just its type/format.

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 'Get[s] detailed product information by ID from the Nexbid marketplace' using a specific verb and resource. It clearly distinguishes from sibling nexbid_search by stating 'Do NOT use for browsing — use nexbid_search instead' and specifying it requires 'a specific product UUID from a previous nexbid_search result.'

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?

Contains an explicit <when_to_use> section stating the prerequisite (having a UUID from previous search) and explicitly naming the alternative tool for browsing (nexbid_search). The <combination_hints> section further clarifies workflow positioning relative to siblings nexbid_search and 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 indicate mutation (readOnlyHint=false) and external interaction (openWorldHint=true). Description adds valuable behavioral context: explains handoff to external retailer ('user clicks to complete the purchase at the retailer'), discloses two distinct output formats (prefill_link vs wallet_pay), and clarifies agent responsibility to 'present this link to the user.'

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 format with clear XML-like sections (tool_description, when_to_use, combination_hints, output_format). Information is front-loaded and logically organized. No wasted words; every sentence provides actionable guidance for tool selection and invocation.

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 no output schema, description thoroughly documents return values in output_format section (checkout URL vs Intent ID). Covers mutation behavior, external retailer handoff, prerequisite workflow, and confirmation requirements. Complete for a purchase initiation 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 has 100% coverage establishing baseline 3. Description adds critical workflow context: specifies product_id must come from sibling search/product tools, and explains checkout_mode selection criteria ('when the user has a connected wallet with active mandate') not evident from schema enum alone.

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 states 'Initiate a purchase for a product' with specific verb and resource. Explicitly distinguishes scope by requiring product UUID from nexbid_search or nexbid_product siblings, clearly differentiating from browsing tools like 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?

Excellent explicit guidance: 'ONLY after user has expressed clear purchase intent' defines when to use. Explicitly names prerequisite tools (nexbid_search/nexbid_product). Includes 'ALWAYS confirm with user before calling' as guardrail. Combination hints map full workflow and specify checkout_mode conditions.

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 readOnly/idempotent status, while the description adds valuable behavioral context: results are 'ranked,' products include 'prices/availability/links' versus recipes with 'ingredients/targeting signals/nutrition,' and output formats vary by intent (Markdown table for compare, bullets for others). It does not mention rate limits or authentication requirements.

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?

Despite being lengthy, the description is well-structured with clear XML-like sections (tool_description, when_to_use, intent_guidance) that front-load critical information. Every section provides distinct value without redundancy, though the format is more verbose than plain text.

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 (11 parameters, multiple content types, four intent modes) and lack of output schema, the description comprehensively covers return formats, sibling relationships, parameter interactions, and session management through previous_queries. No critical gaps remain.

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

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

With 100% schema description coverage (baseline 3), the description adds significant semantic value through the <intent_guidance> section explaining how each enum value (purchase/compare/research/browse) affects behavior, and <combination_hints> explaining the session-based use of previous_queries for multi-turn refinement.

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 'Search[es] and discover[s] products AND recipes in the Nexbid marketplace' with specific verbs and dual resources. It clearly distinguishes from siblings by stating 'For known product IDs use nexbid_product instead' and 'For category overview use nexbid_categories first.'

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

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

The <when_to_use> section explicitly designates this as the 'Primary discovery tool' and provides clear alternates: use nexbid_product for known IDs and nexbid_categories for category overviews. The <combination_hints> section further clarifies workflow sequences (e.g., 'After search with purchase intent → 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?

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?

Annotations provide readOnlyHint=false, destructiveHint=false, etc., but the description adds valuable behavioral context beyond annotations: it explains billing amounts per snippet tier (2¢ to 50¢ CHF), mentions budget decrement and ledger creation, and notes platform fees in output—details not covered by structured annotations, though it doesn't address rate limits or auth needs.

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-loading key info, and each sentence adds value (e.g., billing details, combination hints). It's slightly verbose but efficient overall, with no wasted 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 (billing, ledger updates) and lack of output schema, the description provides excellent completeness: it explains the tool's purpose, usage context, behavioral traits (pricing, budget impact), output format, and sibling relationships, covering all necessary 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%, so the schema already documents all parameters well. The description adds minimal parameter semantics beyond the schema, such as implying 'snippet_type' ties to billing tiers, but doesn't elaborate on 'data_fields' or 'agent_id' usage. Baseline 3 is appropriate given 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 ('track delivery', 'bill the advertiser') and resources ('enriched snippet', 'media buy budget'), and distinguishes it from siblings like 'activate' or 'get_campaign_report' by focusing on billing and ledger creation after delivery.

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 delivers enriched content from a media buy') and provides pricing tiers, while <combination_hints> clarifies its relationship with siblings like 'activate' (for initiating buys) and 'get_campaign_report' (for viewing results), offering clear alternatives and context.

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