discovery

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.