bitroad-mcp
Server Quality Checklist
Latest release: v1.0.0
- Disambiguation5/5
Each tool targets a distinct resource and action, with clear separation between buyer, seller, and service workflows. Despite the large number, there is no overlap or ambiguity.
Naming Consistency4/5Tools follow a consistent domain_verb_noun pattern (e.g., seller_create_listing, disputes_withdraw), with a few minor deviations like auth_whoami and seller_onboarding_status that don't break the overall convention.
Tool Count1/565 tools is far beyond any reasonable scope for a single MCP server, vastly exceeding the typical 3-15 range and even the 50+ threshold for extreme mismatch.
Completeness4/5The tool surface covers the marketplace lifecycle comprehensively—catalog, orders, returns, disputes, services, and auth—but has minor gaps such as no direct order cancellation for buyers or payout management for sellers.
Average 4.3/5 across 65 of 65 tools scored. Lowest: 3.2/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations carry no safety hints (all false), so the description must disclose behavior. It mentions the constraint 'Resulting stock must remain >= reserved' but does not explain error behavior on violation, atomicity, or permission requirements. For a mutation tool, this is insufficient transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences. The primary action is front-loaded, and parameter guidance follows immediately. No wasted words or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter mutation with no output schema, the description covers the core usage and the key constraint. It does not discuss error handling or return values, but these are not essential given the schema and simplicity. Slightly incomplete but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are already documented. The description reinforces the choice between stock and delta and reiterates the reserved constraint, but the schema already states these details. The description adds minimal new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Update a listing's stock count') and clarifies the two modes of operation. It is clear but does not explicitly differentiate from sibling seller_update_listing, which might also modify stock among other fields. The focus on stock count distinguishes it reasonably.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this tool over alternatives like seller_update_listing or seller_create_listing. The description only explains parameter usage, not selection criteria or prerequisites. An agent must infer when stock-only updates are appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (mutation) and idempotentHint=false. The description adds the authorization requirement (respond_dispute action), which is valuable context beyond annotations. However, it does not mention side effects, reversibility, or the impact on dispute status, leaving behavioral transparency incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, focused sentence that states purpose, auth requirement, and input constraint without fluff. Front-loaded with the core action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation with 2 parameters and no output schema, the description covers the core purpose and auth. However, it lacks usage context (when to use vs siblings) and side-effect information, which is necessary for a complete picture. The tool is low complexity, so this is a modest gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both 'text' and 'dispute_id' already have descriptions. The description repeats the length constraint ('Free-form text 1–4000 chars') that the schema's minLength/maxLength already specifies, adding little new meaning. Baseline 3 is appropriate when schema fully describes parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a 'Seller-side response to a dispute', using a specific verb ('respond') and resource ('dispute'). It also distinguishes from sibling tools like disputes_file, disputes_get, and disputes_add_evidence by explicitly framing it as the response action. The auth requirement adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus other dispute-related tools (e.g., disputes_add_evidence, disputes_withdraw). It does not state conditions for use or alternatives. The only hint is 'Seller-side', but it does not clarify the decision boundary with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the read-only annotation, the description discloses pagination behavior and rating semantics, which is helpful. But it fails to mention that the filter instruction is not represented in the actual input schema, and it does not describe the output structure or any potential error cases, leaving some ambiguity about actual behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, using two sentences to cover the core purpose, a filtering tip, and rating guidance. There is no redundant or unnecessary wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives useful context about pagination and prioritization, but because there is no output schema, it should have described what a review object contains (e.g., `rating`, `responded`). The filter inconsistency also leaves the agent uncertain about how to actually retrieve unresponded reviews.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both schema parameters (`cursor`, `page_size`) are adequately described in the schema itself, but the description's instruction to filter by `responded: false` implies a parameter that does not exist in the input schema. Since `additionalProperties` is false, this guidance cannot be followed literally, which is misleading and undermines the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists reviews left on a seller's orders and that results are paginated, which precisely identifies the resource and action. It also differentiates this from related seller-order tools by specifying this is about reviews, not orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance to filter by `responded: false` to find unreviewed responses and notes that lower ratings are higher priority, which helps the agent decide when to use this tool. However, it could be clearer about when to prefer this over `seller_respond_to_review` or `orders_list`, though the intent is reasonably inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool changes a quote's status, and annotations indicate it is non-destructive and not idempotent. It does not mention error cases or return behavior, but given the simple action and lack of output schema, the provided transparency is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that conveys the core action, the actor (seller), the target state, and a prerequisite. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple status-transition action with one parameter and no output schema, the description provides the essential context: seller-side, paid quote, target state, and a required permission. It is nearly complete, though a brief note on expected effects could make it fully exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter is fully described in the JSON schema as the UUID of the paid quote thread, which provides high schema coverage. The tool description does not add much beyond this, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('mark'), the resource ('a paid quote'), and the resulting state ('in_progress'), while also identifying the seller-side perspective. This distinguishes it from related quote actions like accept, reject, or withdraw.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (after a quote is paid and before work begins) and notes a required permission ('Requires the delegation's respond_quote action'). However, it does not explicitly contrast with sibling tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the read-only, non-destructive nature of the search and summarizes the output shape (paginated summaries, pence-denominated prices, stock, restricted-goods flags). It does not detail pagination or error behavior, but annotations already cover safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point, with no fluff. It front-loads the core purpose and then adds the most relevant output and query-format details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 13 parameters, nested objects, and no output schema, the description is somewhat minimal. It mentions pagination and key output fields but omits context on required-with-default parameters and typical pagination flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all 13 parameters with 100% coverage, so the baseline is 3. The description adds little beyond general query guidance and output emphasis; it does not clarify the unusual required-with-default parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool searches marketplace products by free-text, category, or seller, and returns a paginated list of summaries. It is specific and distinguishes the tool from single-product or services-oriented siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides useful query guidance ('Pass a concise phrase, not a full sentence') and names the main filters, but it does not explicitly contrast with sibling search/list tools such as catalog_get_product, seller_list_listings, or services_search_listings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description adds minimal behavioral detail. It focuses on output content rather than side effects, errors, or permissions, which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that conveys the tool's purpose and key output details without unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch operation with one required parameter and no output schema, the description adequately covers what the tool does and what it returns. The annotations cover safety and idempotency, so nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully described in the schema as 'UUID of the service listing to fetch,' and the description does not add further detail. Schema coverage is 100%, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly identifies the resource as a single service listing. It further clarifies what is included—scope schema and fixed-price formula—which distinguishes it from search or seller-specific listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a specific service listing ID is known and full listing details are needed, but it does not explicitly contrast with sibling tools such as services_search_listings or seller_get_listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the core write behavior and the effect of is_default_shipping, going slightly beyond the annotations. It does not discuss idempotency or failure modes, but the create action is clearly conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loads the primary action, and avoids unnecessary detail. It is concise and well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the detailed schema, gives enough context to invoke the tool correctly. It does not describe the return value, but no output schema is provided and the action is simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all parameters, so the tool description adds little beyond restating the default flag behavior. Schema coverage is 100%, so baseline is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves a new shipping address, which is a specific verb-resource action. The sibling tool addresses_list is distinct, and the name and description leave no ambiguity about the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when creating a new shipping address, but it does not explicitly contrast with addresses_list or mention when an alternative should be used. The guidance is adequate but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description does not add extra behavioral context beyond what annotations provide, but it does not contradict them either. Since annotations are present, the baseline is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, containing only necessary information in a single sentence. It effectively communicates the purpose and filtering capability without any irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core functionality and clearly distinguishes buyer/seller sides. It does not describe the response format, but since there is no output schema and this is a straightforward list endpoint, the omission is minor and acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides complete descriptions for all three parameters (cursor, status, page_size), including enum values and default ranges. The tool description does not add additional parameter information beyond the schema, so the baseline is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: listing disputes for the authenticated principal, with explicit clarification of buyer-side vs seller-side disputes. This is specific and actionable, and the verb 'list' is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to get a list of disputes) and provides a filtering option by status. It does not explicitly contrast with disputes_get (single dispute) or other dispute-related tools, but the list vs. single distinction is generally clear from the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully disclosed. The description adds the pagination trait ('paginated') and the filtering behavior, which are useful beyond the annotations. No contradictions with annotations exist. It does not detail pagination mechanics (e.g., next_cursor), but that is documented in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List returns...') followed by concise filter guidance. No wasted words; every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated list tool with full parameter documentation in the schema and safety covered by annotations, the description is complete enough. It clarifies the buyer-side scope and filtering options. The absence of an output schema is acceptable because it is a list operation, and the description plus schema cover the necessary invocation details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, meaning all four parameters have descriptive comments in the schema. The description reiterates order_id and status filters but adds no new semantic meaning beyond what the schema already provides. Baseline 3 applies since the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('returns') with a clear scope: 'authenticated principal filed (buyer-side view)'. It distinguishes from the seller-side sibling tool (seller_list_returns) by explicitly labeling the buyer-side perspective, so an agent can tell them apart without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('List returns the authenticated principal filed') and explains filter usage ('Filter by order_id to find returns on a specific order, or by status'). It implies the buyer-side view, which differentiates it from seller_list_returns, though it does not explicitly name the alternative tool or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses idempotent no-op behavior and the automatic enqueueing of carrier polling. It does not exhaustively describe all side effects, but the annotations already cover read-only/destructive hints, so the additional context is valuable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary action, and contains no filler. The idempotency and side-effect details are included in two tight sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary purpose, idempotency, and a key side effect, while the schema supplies required parameters and constraints. It does not mention error conditions or return values, but these are not essential for a basic call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for all parameters, including a clear explanation of the tracking_number idempotency. The tool description adds little beyond what is already present in the parameter schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Mark an order as shipped with a tracking number,' which is a specific action and distinguishes it from related tools like seller_mark_delivered or seller_attach_tracking. The scope is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the core behavior and idempotency, but it does not explicitly say when to use this tool over alternatives such as seller_mark_delivered or seller_attach_tracking. Usage context is implied but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description correctly does not repeat safety. It adds behavioral detail about the stale: true flag when trust metrics are older than 36 hours, which is useful context beyond annotations. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the primary purpose and then adds the trust signal detail and staleness behavior. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only tool with no output schema, the description covers the return content (profile + trust signals) and a notable edge case (stale flag). It is adequate for an agent to call correctly, though it could mention exact output structure if needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes the sole parameter seller_id with a clear description ('UUID of the seller whose public profile to fetch'). Schema description coverage is 100%, so the description adds no additional meaning about the parameter. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a seller's public profile plus trust signals, with specific verb and resource. It distinguishes from siblings like seller_get_me (which likely fetches own profile) by implying it's for any seller by ID, and the mention of trust signals adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool vs alternatives such as seller_get_me. It implies it fetches any seller's public profile, but there is no guidance on when to choose this over other seller-related tools. The presence of seller_get_me suggests a distinction, but it's not articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description adds useful behavioral detail: specs are re-validated, return_policy is re-validated against statutory floors, and buyer intents are re-validated at confirm time rather than blocking the update. This gives meaningful transparency without contradicting the supplied annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no fluff. It front-loads the core action and ownership restriction, then adds the validation and deferred-intent behavior in a compact, structured way.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives enough context for the core operation and key validation behavior, and the schema covers parameter details and partial-update semantics. It does not describe response or error behavior, but there is no output schema, so that omission is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all parameters, so schema coverage is 100%. The description adds little new parameter-level meaning beyond restating that specs and return_policy are re-validated, which is already reflected in their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool patches an existing listing owned by the calling seller, giving a specific verb, resource, and ownership scope. It is readily distinguishable from sibling tools like seller_create_listing, seller_archive_listing, and seller_update_stock.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by saying 'Patch an existing listing the calling seller owns', but it does not explicitly compare against or exclude alternatives such as seller_update_stock or seller_create_listing. The deferred-revalidation note gives some context but not direct tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations, such as the Stripe onboarding requirement and refusal with 'stripe_onboarding_incomplete,' and notes that haggling_enabled is ignored for fixed-price listings. This goes beyond the basic readOnly/destructive flags in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is packed with useful information and structured around key concepts (pricing modes, scope schema, Stripe requirement). While it is dense, it remains focused and avoids unnecessary filler, earning a high score for conciseness given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (18 parameters, nested objects, no output schema), the description adequately covers essential context: the purpose, pricing modes, scope DSL, and a key error condition. It does not mention every edge case, but it provides enough for an agent to decide when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema descriptions cover 100% of parameters, the description adds relational context, such as how fixed_unit_* fields must be set together and how scope_schema constrains buyer requests. This enriches the schema's individual parameter descriptions without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Seller-side: publish a service listing.' It specifies the resource (service listing) and the action (publish), and distinguishes it from buyer-side tools by listing service categories like GPU compute and synthetic data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some usage conditions (e.g., requires completed Stripe onboarding) and explains the fixed vs. quote pricing modes, but it does not explicitly differentiate this tool from the sibling 'seller_create_listing' or state when to prefer one over the other. Alternatives are not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate read-only, idempotent, non-destructive behavior. The description adds useful detail about what is returned and how the behavior differs between instance keys and OAuth tokens (null OAuth-specific fields), exceeding the annotation baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant wording. It front-loads the core purpose and then adds relevant conditional detail about token types, all while remaining easy to read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the returned fields and the distinction between instance keys and OAuth tokens. It does not mention possible failure modes (e.g., invalid/expired credential), but for a simple identity inspection tool with no parameters and no output schema, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema has no properties, so the baseline score of 4 applies. The description provides no parameter details because none exist, and this is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 ('Return') and identifies the resource as the current MCP credential identity. It lists the returned fields (principal email/role, agent name, client, last-used timestamp), making it easy to distinguish from other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: call it to inspect the current credential identity. It does not explicitly contrast with sibling tools like auth_revoke_self, nor does it state when this tool is preferred over alternatives, but the read-only intent is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the schema is included only for leaf categories, which is a behavioral nuance beyond the read-only, idempotent annotations. This adds helpful detail about what the response will contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and directly to the point, with no unnecessary words or redundancy. It efficiently conveys purpose and usage context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description sufficiently covers what the tool does and when to use it. It could mention error cases or non-leaf behavior, but the provided context is adequate for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'slug' is fully described in the input schema with a minLength and example. The description does not add additional meaning beyond the schema, so a baseline score of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'one category by slug', with the additional detail of including the spec JSON Schema for leaf categories. This distinguishes it from sibling tools like catalog_list_categories and catalog_get_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when it is useful ('before building a structured purchase intent') and why ('so the agent emits a valid spec query'), providing clear contextual guidance. It does not explicitly state when not to use it, but the use case is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which are the core behavioral facts the caller needs about side effects. The description adds edge-value context by naming 'live stock' and flags in the return, but it does not disclose anything like auth requirements, rate limits, or error behavior, so a mid-range score is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The definition is a secure two-sentence structure: the first sentence states the action and key return fields; the second sentence gives a routing decision. Every word earns its place, and the practical guidance moves to the front.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter get tool with no output schema, the description covers the main return areas well and gives guidance. It does not describe error handling, but with one param and simple semantics this is not a significant gap. Compared to the cursory does-list, this feels complete for the intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and product_id is already fully documented with type, format, pattern, and a description. The description adds no new parameter semantics; it merely refers to 'by id', which is already present. Baseline 3 is correct with no redundancy above it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Fetch a single product by id') and enumerates what is returned. It distinctively covers the difference between a detail view and a search operation by naming search as the thing to avoid, so the tool can be told apart from catalog_search_products without inspecting either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence explicitly tells the agent when to use this tool and when not to: it should not be used by re-running search when the product id is already known. This directly references the main alternative (search) and gives a clear decision condition, so an agent can route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds context by stating the consequence (releasing stock reservation). This adds value beyond the annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence that front-loads the action and effect with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with destructive annotation, the description is complete enough to guide correct invocation. It lacks error-handling details, but these are not critical for this simple operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single parameter (intent_id) is fully documented in the schema. The description does not add extra parameter details, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Cancel a pending purchase intent') and a clear effect ('release the stock reservation'). It clearly distinguishes from siblings like purchase_create_intent and purchase_confirm_intent by specifying the cancel step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by limiting to 'pending purchase intent', but it does not explicitly mention exclusions or alternatives (e.g., not for confirmed intents). This is adequate but not explicit enough for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and readOnlyHint=false, but the description adds the specific state change and the asynchronous refund via webhook, which is valuable behavioral context beyond the annotations. It does not contradict any annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the core action, followed by the state transition and side effect. Every sentence adds value with no redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation with no output schema, the description covers the action, state transition, and side effect. It implies the precondition (return must be in 'approved' state) through the transition. It does not describe the response or error cases, but the idempotency annotation and the simplicity of the operation make this sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions already cover both parameters with detailed meaning (return_id explains acceptance and immediate refund; inspection_notes explains its optional nature and limit). Schema coverage is 100%, so the tool description adds no extra parameter-specific information, placing it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action (acknowledge arrival and inspection) and the exact state transition (approved → received), which clearly distinguishes it from sibling seller_reject_return. It also mentions the refund engine, giving a complete picture of the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool (when the parcel has arrived and been inspected) by describing the precondition for the state transition. However, it does not explicitly name alternatives like seller_reject_return or state when not to use it, though the sibling list makes the distinction implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds valuable context by clarifying it's a soft delete (not a hard delete) and by stating the refusal condition for pending purchase intents. This goes beyond the annotation's bare destructive flag.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The primary action and its key constraint are front-loaded, making the purpose immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter operation with annotations covering the destructive nature, the description provides the essential behavioral detail (soft-delete and refusal condition). The lack of an output schema is acceptable, and nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema's description for product_id already includes the refusal note. The tool description repeats this information without adding new parameter-specific meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Soft-delete a listing (is_active=false)', which specifies the verb, resource, and effect. It also distinguishes itself from other seller tools by highlighting the refusal condition, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear condition for when the tool can be used: 'Refuses while any purchase intents are still pending against it.' This provides contextual guidance but does not explicitly mention alternatives like seller_update_listing or when to choose this over other listing modification tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds meaningful context beyond that: the default inclusion of archived/flagged listings and the behavior of the is_active filter, plus expected output fields. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with zero redundant phrasing. The main purpose is front-loaded, followed by key behavioral details and output expectations. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated list tool, the description covers default behavior, filtering, and output fields. The schema handles cursor and page_size definitions. It doesn't explicitly mention the response structure (e.g., next_cursor), but given no output schema and typical API conventions, the definition is complete enough for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are documented in the schema. The description echoes the is_active filter's effect, but the schema already states it. No additional semantic meaning is provided beyond what's already in the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('the bound seller's product listings') along with pagination, clearly distinguishing it from sibling operations like seller_get_listing. It also specifies default inclusion of archived/flagged listings, making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (listing all product listings for the bound seller) and naturally separates from siblings by scope (multiple vs single). However, it does not explicitly mention alternatives like seller_get_listing for a single listing, so it stops short of full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-readonly, non-idempotent operation. The description adds the crucial behavioral detail that subsequent attempts return 'already_responded', which is not covered by annotations. This clarifies the non-idempotent nature and provides a specific error condition, adding value beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action and immediately states the key constraint. There is no redundant or filler content; every word contributes to understanding the tool's behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter operation with no output schema, the description is adequate. It covers the action, the uniqueness constraint, and the error case. It does not mention prerequisites like authentication or permission requirements, but these are generally implied for seller tools and not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (review_id and text) already documented. The description does not add any additional parameter semantics beyond what the schema provides. Since the schema fully covers the parameters, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action ('Post the seller's response to a review') with a clear verb and resource. It also adds the key constraint of one response per review, which differentiates it from sibling tools like seller_list_reviews. The purpose is unambiguous and distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool (to respond to a review) and the constraint that only one response is allowed, signaling that the agent should check whether a response already exists. It doesn't explicitly mention alternatives, but the tool's name and sibling context make the usage clear without confusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive. Description adds useful behavioral details about pagination and status filtering, which are beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one clear sentence, no redundant words, and directly conveys the essential functionality. Very well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With four parameters and no output schema, the description sufficiently covers the tool's purpose, pagination, and filtering. It omits details like response fields, but that is acceptable for a simple list operation without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides 100% coverage with clear descriptions for all four parameters, including enums and defaults. Description adds no additional semantics beyond what the schema already offers, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly specifies the action (list), resource (service quote threads), and scope (buyer-side, principal opened). It distinguishes from sibling tools like services_list_my_sales and services_list_open_requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The buyer-side view implies when to use versus seller-side alternatives, but does not explicitly name alternatives or state exclusions. Still, the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which only say it's not read-only), the description adds concrete behavioral consequences: the price band constraint, the 24h SLA, and the required permission. It doesn't describe the return value, but no output schema exists, so this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no waste. The key purpose and scope are front-loaded, followed by the permission, constraint, and SLA consequence. Every sentence contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a submit action with no output schema and minimal annotations, the description covers the essential context: what it does, who it's for, prerequisites, constraints, and a side effect. It doesn't mention the request state, but given the sibling tool family, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameters are already described. The description reiterates price/ETA/terms but adds no new parameter-level meaning; the price band constraint is already in the schema's price_pence description. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('answer a quote request') with a specific resource, and explicitly identifies the seller-side context. It distinguishes this from buyer-side actions like accept/reject and from counter_quote by its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates when to use (seller responding to a quote request) and mentions a prerequisite (respond_quote action). It does not explicitly exclude counter_quote for proposing different terms, but the context is strong enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description conveys that withdrawal is a state-changing action (open → withdrawn) and implies limited applicability (only open disputes). It aligns with the destructiveHint annotation, though it does not detail all side effects (e.g., whether withdrawal can be reversed), which is acceptable for this level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using two short sentences to convey all essential information. No redundant words or unnecessary structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool without an output schema, the description provides sufficient context: who can use it (buyer), what it does (withdraw), and when it is valid (open disputes only). No additional information is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a clear description for the single parameter (dispute_id as UUID of the open dispute), achieving 100% schema coverage. The description adds no extra parameter-specific details, 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.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('withdraw') and the resource ('an open dispute'), distinguishing it from sibling dispute operations like file, list, get, add evidence, and respond. The scope is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the actor ('Buyer-only') and the condition ('open dispute'), explicitly noting that closed disputes cannot be withdrawn. While it does not enumerate when to use alternative dispute actions, the given constraints sufficiently guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond the annotations, such as noting it 'attaches or updates' tracking, but does not describe side effects or auth requirements beyond what the schema already provides. The schema covers replacement of existing tracking, so the description adds little extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The purpose is front-loaded, and the usage guidance follows immediately. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with three parameters and no output schema. The description covers purpose and usage, the schema covers parameters, and annotations cover idempotency and destructive behavior. Nothing essential for an agent to call this tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, so the schema already documents each parameter's meaning. The description does not add parameter-specific semantics, but the purpose statement helps contextualize why these parameters are needed. With full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Attach or update'), a specific resource ('tracking on an already-shipped order'), and explicitly distinguishes from the sibling mark_shipped by noting this is for late-arriving tracking only. This makes the tool's purpose clear and differentiates it from similar tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use this tool versus the alternative: 'Use mark_shipped for first ship; this is for late-arriving tracking only.' This is direct and unambiguous guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive. Description adds the error behavior of refusing when no seller record exists, which is useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence conveys the essential purpose and one key behavior without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description is complete; it covers the main use case and error condition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; baseline score applies. Description correctly avoids inventing parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb 'fetch', resource 'seller record', and scope 'bound to calling principal', clearly distinguishing it from sibling tools that may fetch other sellers or listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied that this is for the current seller, but does not explicitly contrast with sibling tools like 'sellers_get' or 'seller_get_listing'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint true and readOnlyHint false. The description adds minimal extra transparency about side effects beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no redundancy, directly conveying the tool's purpose and special cases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple action and no output schema, the description sufficiently covers the tool's context and usage. Could mention expected state change but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter service_quote_id is fully described in the schema with a clear UUID format and purpose. No gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (reject) and the resource (quote), with specific roles (buyer-only, principal after cap kickback). Distinct from siblings like accept or withdraw.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context for when to use (buyer rejection, principal denial after cap kickback), but does not explicitly contrast with alternative tools like services_withdraw_quote.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral constraints (role and timing) beyond the annotations. The destructive nature is consistent with destructiveHint=true, though side effects (e.g., whether the request is deleted or marked withdrawn) are not detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence with no redundant words. The structure is clean and directly communicates the action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description covers purpose, condition, and role completely. No missing information for a simple withdrawal action.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the parameter with format, required flag, and a clear description. The tool description adds no extra parameter meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('withdraw'), resource ('quote request'), and clarifies role ('buyer-only') and condition ('before the seller has quoted'). Clearly distinguishes from sibling actions like accept, reject, or counter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a temporal condition ('before the seller has quoted') and role restriction ('buyer-only'), which helps the agent decide when to use this tool. Does not explicitly name alternatives, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent operation, but the description adds valuable behavioral details: base64 encoding, per-item and per-dispute size caps, and authorization constraints. These go beyond the structured annotations and help the agent understand operational limits and permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no filler. The core action is front-loaded, followed by key constraints and authorization. Every sentence adds meaningful information, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with five parameters and no output schema, the description covers the essential operational context: the action, the state requirement ('open dispute'), size limits, and who can invoke it. It doesn't explain error handling or response format, but these are not critical given the schema coverage and lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds the per-dispute cap (not present in schema) and clarifies who can perform the action, providing extra context beyond individual parameter descriptions. This justifies a score above the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Attach an evidence item') and the resource ('to an open dispute'). It distinguishes this from sibling dispute tools (disputes_file, disputes_respond) by focusing on evidence attachment, and the verb is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the condition of an 'open dispute' and explicitly states who can upload ('Either the filing buyer or the seller-owner can upload'), giving clear usage context. However, it does not explicitly mention when not to use it or compare with alternative tools, though no direct alternative for evidence addition exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds useful context about pagination via cursor, the optional status filter, and the buyer-side scoping. It doesn't describe the return structure, but given the annotations, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the core action and scope; the second provides the primary use case. It is front-loaded and free of redundancy, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description covers the essential aspects: what it lists, who it lists for, pagination, filtering, and its role in a workflow. It doesn't detail the response fields, but that is not strictly required for a list operation when the annotations already cover safety. 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter thoroughly (e.g., cursor origin, status enum, page_size bounds). The description adds no additional parameter-level meaning beyond confirming the filter is optional and the pagination approach. This meets the baseline but doesn't exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists orders placed by the authenticated principal (buyer-side), distinguishing it from seller-side tools like seller_list_orders. It also mentions pagination and the status filter, and explicitly positions it as a precursor to orders_get. The verb and resource are 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use this to find an order id before calling orders_get.' It also clarifies the buyer-side scope, implicitly contrasting with seller_list_orders. This is direct and actionable, leaving no ambiguity about when 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description's 'Fetch' wording aligns with that. It adds a useful behavioral detail by mentioning that decommissioned platforms include a banner and reason, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, with no filler. The first sentence states the primary purpose and returned fields, while the second handles the decommissioned-platform case, both earning their place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description compensates by enumerating the main response components: KYC status, rolling-window metrics, on-time-ship rate, dispute resolution percentiles, anomaly-pause count, and decommissioned banner/reason. This gives the agent a solid picture of what to expect with minimal ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully describes the slug parameter, and the tool description reinforces that it is a URL slug and explicitly clarifies it is not a UUID. This gives the agent clear guidance on what value to supply.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly identifies the resource: a platform's public reputation profile by slug. It also lists the key data points returned, making the tool's purpose unmistakable and distinct from sibling tools like sellers_get or catalog_get_product.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a consumer needs a platform's public reputation data, but it does not explicitly state when to prefer this tool over alternatives or provide exclusion criteria. The context is inferable from the wording, but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is fully transparent about the read-only, idempotent nature of the operation, the short-lived signed URL, expiry behavior, and the availability precondition. This aligns with the annotations and adds useful operational detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with every sentence providing meaningful detail and no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what is returned (a short-lived signed URL for a PDF), the expiry/refresh behavior, and a key precondition. Since there is no output schema, this is sufficient for most use cases, though error conditions are not described.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, return_id, is fully described by the schema with a UUID format and pattern, and the description repeats that it identifies the return. Schema coverage is 100%, so baseline is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a short-lived signed URL for a return shipping label PDF, making the specific resource and action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly notes that the URL expires within minutes and that re-calling is needed for a fresh one, and it states the precondition that the return must have reached label_ready. It does not compare with sibling tools, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (which only indicate non-read-only and non-destructive), the description reveals important side effects: the restricted-goods classifier runs at write time, and flagged listings are inserted but invisible until cleared. This is critical behavioral info that the annotations do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and to the point, consisting of two sentences. It avoids unnecessary details and focuses on the essential action and notable behaviors, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core action and a key behavioral nuance, but it does not mention what the tool returns or how to interpret the response. Given the absence of an output schema, a brief note on the return value would enhance completeness, but the current level is adequate for a straightforward create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all parameters, achieving 100% coverage. The description does not add any additional parameter-level information, so it aligns with the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's primary action: 'Create a product listing.' It also mentions validation against category spec and return policy, which adds specificity. This distinguishes it from sibling tools like seller_update_listing or seller_list_listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to create a new listing) and gives context on validation steps, but it doesn't explicitly contrast with alternatives like seller_update_listing or services_create_listing. Still, the purpose is clear enough for an agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description adds value by explaining that onboarding is human-on-session and that the tool is a polling read for the charges_enabled flag. This goes beyond the annotations but does not describe the response format or pagination, which is acceptable given the simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant words. The core purpose is front-loaded, and the usage condition is stated succinctly. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description covers the purpose, the condition to wait for, and the human-in-the-loop context. It lacks explicit return value details, but the mention of charges_enabled implies the response shape. This is sufficient for an agent to correctly invoke and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and the schema provides 100% coverage (none). The description references the field 'charges_enabled' which is part of the response, not a parameter, so it adds no confusion. The baseline for zero-parameter tools is 4, and the description is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb and resource: 'Read-only Stripe Connect onboarding status' and mentions the key condition 'charges_enabled flips true', making it distinct from sibling tools like sellers_get or seller_get_me. It precisely identifies the tool's function without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: 'agents wait on this read until charges_enabled flips true before listing', which tells the agent when to use this tool and for what purpose. It does not explicitly name alternative tools, but the context of waiting and the human-on-session note clarifies its role in the onboarding flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully discloses the tool's side effects: it 'validates the scope, computes the deterministic price, creates the quote thread directly in accepted, and charges immediately.' It also notes that it operates without human seller interaction. This goes beyond the annotations (which only indicate false readOnly and idempotent) by specifying the actual state-changing operations performed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first clearly states the main action and internal behavior, and the second provides a useful cross-reference to a sibling tool. It is concise, front-loaded, and free of fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (multiple parameters, confirmation flow hinted in the schema), the description covers the primary purpose and high-level behavior well. It does not explicitly mention the confirmation_required kickback flow or that a retry may be needed, but these details are present in the schema and annotations, so the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema itself has 100% parameter description coverage, so the tool description does not need to repeat parameter details. However, the tool description adds no parameter-level meaning beyond what is already in the schema. Since coverage is high, the baseline is 3, and there is no additional parameter insight to warrant a higher score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Buy a fixed-price service in one call.' It specifies the resource (fixed-price service) and the action (buy), and distinguishes it from quote-based flows by noting 'no human seller round-trip' and 'creates the quote thread directly in accepted.' This makes it immediately obvious when to use this tool versus quote-based alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: for fixed-price services with immediate purchase and no negotiation. It also references 'Same delegation/envelope enforcement as services_accept_quote' for payment handling. However, it does not explicitly state when not to use it (e.g., when a listing requires manual quote approval), so it lacks an explicit exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the workflow and the fixed-price refusal behavior, which goes beyond the minimal annotations. It does not mention idempotency or repeat-request effects, but the core side effects are reasonably clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, direct, and packs essential distinctions and workflow details without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description gives sufficient context about the request lifecycle and edge case (fixed-price refusal). It could mention how to retrieve the resulting seller response, but the sibling tools make that discoverable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all three parameters with descriptions, so the description adds little extra parameter-level meaning. It does reinforce that scope must conform to the listing's scope schema, but the schema itself already states this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: filing a scope-of-work against a quote-mode service listing. It also explicitly distinguishes this from services_purchase for fixed-price listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit guidance on when to use the tool (quote-mode listings) and when not to (fixed-price listings, directing to services_purchase). It also outlines the expected flow: seller responds with price + ETA, buyer has 24h to accept.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds valuable behavior context by explaining the semantic difference between 'fixed' and 'quote' listings and what each implies for the purchase flow, going beyond what the schema or annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: the first front-loads the core purpose and scope, the second explains the key filter and its behavioral implications. No wasted words or redundant information—every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema, the description adequately covers the essential distinction between fixed and quote listings, which is critical for deciding next steps. It doesn't describe the response structure, but that is often not needed for a search tool, and the pagination cursor is documented in the schema. Given the tool's simplicity, this is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds semantic meaning to pricing_mode by explaining the distinction ('fixed' = one-call purchase, 'quote' = requires quote first), and it also lists the category values, reinforcing the enum. This enhances parameter understanding beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search') and resource ('agent-to-agent service listings'), and lists specific categories (GPU compute, synthetic data, etc.). It clearly distinguishes this from sibling tools like seller_list_listings (seller's own listings) and services_get_listing (single listing) by focusing on searching across all listings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how pricing_mode affects the subsequent workflow ('fixed' listings are buyable in one services_purchase call; 'quote' listings need a seller quote first), giving clear context for when to use this search and what to do with results. It does not explicitly state when to avoid this tool in favor of, say, catalog_search_products, but the scope is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations by detailing exact idempotent behavior: 'a second call returns `{ revoked: false, reason: 'already_revoked' }`' and clarifies the error case for br_ik_* keys. It also specifies that both access and refresh tokens are revoked, which is not in the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, three sentences total, with the primary purpose front-loaded. It includes only essential details about idempotency and error conditions, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple zero-parameter tool, the description fully covers functionality, idempotency, and error handling. It also provides actionable guidance for the br_ik_* key case, making it contextually complete without needing return-value details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with zero parameters, so schema coverage is high (100%). The description adds no parameter-specific information, which is appropriate given there are none. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Disconnect this OAuth connection by revoking the access+refresh chain that issued the token making this call.' It uses a specific verb (revoke) and resource (OAuth connection), distinguishing it from sibling tools like auth_whoami.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when not to use it: 'Refuses with not_oauth_token when called under an br_ik_* instance key — rotate those from the dashboard instead.' It implies use for OAuth tokens, though it does not explicitly compare to alternative auth tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is already covered. The description adds valuable behavioral context beyond that: it tells the agent that the response shape matches envelopes_list and that a 404 occurs when the envelope is not bound to the calling agent instance, which is exactly the kind of behavioral nuance that an agent needs to be prepared for.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences: the first clearly states the primary action, the second provides the return shape, and the third gives an edge-case. No fluff, each sentence earns its place, and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter getter with no output schema, the description is complete. It communicates the primary use, the return shape, and the key 404 error scenario. The annotations already cover safety and idempotency. Nothing critical is missing for an agent to call this tool correctly and handle the outcome.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers the envelope_id parameter fully with a clear 'description' field. The tool description mostly repeats the 'by id' notion but does not add semantic meaning beyond the schema. The parameter is simple and well-documented in the schema, so the description doesn't need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (fetch), a specific resource (a single envelope), and the identifier used (id). It distinguishes itself from its sibling envelopes_list both in particle size (single vs. list) and by referencing the same return shape, so an agent can tell them apart immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to retrieve one envelope by ID. Although it doesn't explicitly say 'use envelopes_list for multiple envelopes', the single-by-id framing strongly implies the correct condition. Not having an explicit alternative is a minor omission, but the intended scope is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description and annotations align by marking the operation as read-only and non-destructive. The description adds that envelopes are created by the principal, reinforcing that this tool has no side effects. No contradictions or hidden behaviors 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two focused sentences. It includes necessary context about what envelopes are listed and the key fields shown, without any redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple list operation with no parameters or output schema, the description provides complete context. It explains the envelope scope, the typical use case, and the data fields returned, leaving no important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description does not need to explain parameter details. The baseline score of 4 applies since there are no parameter semantics to elaborate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists active and historical payment envelopes, with a specific resource and scope. It distinguishes itself from the related envelopes_get tool by focusing on listing rather than retrieving a single envelope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the envelopes are those the calling agent can draw against, providing clear context for when this tool would be useful. It does not explicitly name alternative tools, but the listing vs. getting distinction is implied and sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, establishing a safe, read-only operation. The description adds context about the buyer-side scope and the breadth of data returned (line items, tracking, payments, returns/disputes), which goes beyond a bare 'get' call. It does not contradict annotations and provides useful behavioral context for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler. The main functionality is front-loaded, and the alternative is given in the second sentence. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only tool with annotations covering safety, the description is complete: it states what data is returned, clarifies buyer vs. seller scope, and points to the alternative. No critical information for invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully describes the single parameter order_id as 'UUID of the order to fetch' (100% coverage). The description does not repeat parameter details, and since schema coverage is complete, the baseline of 3 is appropriate. No additional parameter semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Fetch'), a precise resource ('a single order'), and enumerates the included data (line items, shipment/tracking, payment status, returns/disputes). It also differentiates itself from seller_get_order, making its scope unambiguous even without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Buyer-side view — for seller-side use seller_get_order.' This directly tells the agent when to use this tool and when to use an alternative, leaving no ambiguity about the buyer/seller distinction. The guidance is concise and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral aspects: no charge is made (setup mode only), the card is saved automatically upon completion, and the agent's role is limited to presenting the URL. This goes beyond the annotations which only indicate non-read-only, non-destructive behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. It provides necessary details about the return value and the agent's action, though the second sentence slightly repeats the instruction about presenting the URL. Overall, it is well-structured and not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no parameters and no output schema, the description sufficiently covers the context: the purpose, the setup mode, the no-charge aspect, and the agent's next steps. It does not mention edge cases (e.g., existing cards), but the essential information for using the tool is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters in the input schema, so there are no parameter semantics to describe. The description does not need to explain any parameters, and the baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: returning a one-time Stripe Checkout URL for adding a payment card. It also specifies that it is setup mode only and that the card is saved automatically, distinguishing it from payment_methods_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on what to do with the response (present the checkout_url to the user) and states that there is nothing else for the agent to do. It also notes that only buyer principals should use this tool. However, it does not explicitly name an alternative tool, though the context among siblings makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses important side effects: price re-validation, charging the buyer, creating the order, and possible SCA/declined/provider errors. This goes beyond the annotations, which only mark the tool as non-read-only and non-idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single compact sentence covering purpose, key behavior, and error types without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description sufficiently explains what the tool does and what errors may occur. It provides enough context for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions, so the description adds little beyond the schema. The confirmation_token and acknowledged_confirmation fields are already well documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool confirms a purchase intent, with specific actions: re-validating price, charging via Stripe Connect, and creating the order. This distinguishes it from sibling tools like purchase_create_intent and purchase_cancel_intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the confirmation flow and possible error outcomes, making its use context clear. It does not explicitly contrast with alternatives such as purchase_cancel_intent, but the confirmation-focused wording is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important side effects: stock reservation, price/VAT/shipping snapshot, delegation policy consultation, intent expiry, and the postage implications of creating multiple intents. This goes well beyond the annotations, which only indicate non-read-only and non-idempotent behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is focused and front-loaded with the primary purpose. The additional sentences about expiry and combined postage are relevant and necessary for correct usage, with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema, the description adequately explains what the caller receives (an intent id), the temporal validity, side effects, and a key behavioral warning. This is sufficient context for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for all four parameters and covers 100% of them. The description does not add significant parameter-specific meaning beyond the schema, so it stays at the baseline for schema-covered parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Create a purchase intent for a product.' It also distinguishes this tool from related siblings like purchase_confirm_intent and purchase_cancel_intent by focusing on the creation step and returning an intent id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear operational context: reserves stock, snapshots pricing, consults delegation policy, expires after 15 minutes, and includes combined postage guidance. It does not explicitly say 'use this instead of confirm/cancel' but the lifecycle details make the intended usage obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds a nuance that the inspection trail is only available after arrival, which is helpful behavioral context. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with no filler. Every word contributes to explaining the tool's purpose and expected response contents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool, the description fully covers what the agent needs: the parameter, the resource type, and the key response fields. No output schema is provided, but the description compensates by listing the included data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter return_id is fully described in the schema as 'UUID of the return to fetch.' The description reinforces 'by id' without redundancy, clearly linking the parameter to the action.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Fetch a single return by id') and enumerates the response contents (reason, status, restocking fee, refund ledger, inspection trail). This distinguishes it from sibling tools like returns_list and returns_get_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly indicates usage for a single specific return rather than a list, and notes 'once the parcel has arrived' which hints at timing. Does not explicitly name alternatives, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is highly transparent about side effects and consequences: it creates a return, triggers a seller-funded label obligation, may lead to auto-refund, and states idempotency on order_id. This goes well beyond the annotations (readOnlyHint: false, idempotentHint: true) and gives the agent a clear picture of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is unnecessarily verbose and redundant. The full policy (30-day window, free, full refund, no restocking fee, seller funds label) is repeated nearly verbatim twice. The first paragraph already conveys all necessary information; the second paragraph adds no new content. This reduces clarity and increases token usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (3 params, 1 enum, no output schema), the description covers all essential context: initiation condition, policy rules, reason semantics, post-return obligations (label upload, auto-refund), and idempotency. No critical operational detail is missing for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the tool description adds meaningful policy context for the reason enum (e.g., cooling_off_statutory corresponds to days 0–14 change-of-mind, defective is a CRA 2015 claim). This enriches the schema's per-parameter descriptions and clarifies how each reason affects the return process.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Initiate a return on a delivered order.' It distinguishes this state-changing action from read-only sibling tools like returns_get, returns_list, and returns_get_label by using the verb 'Initiate' and specifying the precondition (delivered order).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear when-to-use condition ('on a delivered order') and details the applicable policies (30-day window, free return, seller-funded label). It does not explicitly mention alternatives such as returns_get or seller_accept_return, but the sibling context and verb 'Initiate' make the intended usage clear. A minor gap is the lack of an explicit 'do not use for read-only checks.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by revealing the ownership check ('refuses if the listing belongs to a different seller') and the exact data fields returned, which are not implied by annotations or schema. This is substantive behavioral disclosure beyond 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the primary action and resource, then lists the key return fields and the refusal condition. Every clause earns its place; there is no fluff or redundancy, making it optimally concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with full schema coverage and annotations covering idempotence and non-destructiveness, the description is complete: it states what is returned, the ownership constraint, and the refusal behavior. No output schema exists, but the description enumerates the content sufficiently. Nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter product_id is well-described as a UUID. The description enriches this by clarifying that the UUID must correspond to a listing owned by the bound seller, adding a semantic constraint not present in the schema's description. This is meaningful additional guidance for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('fetch'), a precise resource ('a single listing the bound seller owns'), and enumerates the returned contents (description, stock/reserved counts, spec values, moderation state). This clearly distinguishes it from sibling tools like seller_list_listings (list all) and catalog_get_product (public product info), leaving no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description defines the scope as the bound seller's own listings and explicitly notes it refuses other sellers' listings, giving clear context for when it applies. It doesn't name alternative tools for other cases (e.g., public product lookup), but the ownership constraint effectively guides usage for seller-scoped retrieval, so it's nearly complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses side effects beyond the annotations: it notifies the buyer (who can dispute) and notes that orders auto-mark after 10 days. It also clarifies that no carrier confirmation is wired, which is not implied by the annotations. This adds meaningful behavioral context without contradicting the idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with zero redundancy. It front-loads the core action, then provides constraints and side effects, all essential. No filler or extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with rich annotations, the description covers the purpose, valid state transition, side effects, and platform auto-behavior. Since there is no output schema and the parameter is fully described in the schema, nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the single parameter with a clear description ('UUID of the shipped order to declare delivered. Already-delivered is a no-op success.'). The main description repeats the no-op aspect but does not add new semantic meaning beyond the schema, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Declare' and the resource 'shipped order' with the action 'as delivered', and specifies it has no carrier confirmation. It is distinct from siblings like seller_mark_shipped and seller_attach_tracking, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit precondition ('Only valid from shipped') and explains the no-op behavior on already-delivered orders. It also mentions the 10-day auto-mark, giving clear context for when to call. It does not name alternative tools, but there is no obvious sibling for this exact action, so the guidance is adequate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral details beyond the annotations (destructiveHint, readOnlyHint) by noting the 'Refuses if already refunded' condition and that inspection_notes is shared with the buyer. This enriches the understanding of side effects without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, direct and free of fluff. It front-loads the purpose and then adds a condition, making it easy to scan and understand immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the absence of an output schema, the description covers the essential context: what action, when it applies, and a key constraint. It does not mention post-rejection status changes, but this is minor and covered by the destructiveHint annotation. Overall, it is 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.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema with clear semantics: return_id is a UUID identifying the return, inspection_notes includes a length constraint and explains it is the reason shown to the buyer. The tool description also reiterates that inspection_notes is required, aligning perfectly with the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Reject a return'), the context ('after inspection'), and a key condition ('Refuses if the return has already refunded'). This distinguishes it from sibling tools like seller_accept_return, returns_initiate, and returns_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides contextual guidance by specifying 'after inspection' and the refusal condition. While it does not explicitly name alternatives, the action and condition make it clear when to use this tool. Slightly more explicit comparison could elevate this, but it is already informative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description thoroughly discloses side effects: the acknowledgement is recorded immediately, the held payout releases based on settlement timing, and the status remains 'delivered' until funds settle. It also explains the default auto-release behavior, providing clear transparency about state changes and timing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: one sentence for the action, one for the consequences. No redundant or irrelevant detail, and the information is presented logically without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it is a single action with side effects, the description covers the primary outcome, the conditional funding release, and the default behavior if not invoked. It does not mention errors or response structure, but the absence of an output schema makes that acceptable. The context is sufficiently complete for an agent to decide and act.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description already clearly states 'UUID of the delivered quote thread to accept.' The tool description does not add extra parameter semantics beyond restating 'delivered quote', so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Explicitly accept the deliverable on a delivered quote.' The verb 'accept' and resource 'deliverable' are specific, and the context distinguishes it from related tools like services_accept_quote (accepting a quote before work) and services_submit_deliverable (seller submission).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it: when a quote has been delivered and you want to accept it. It explains the consequence of not using it (auto-release after 7 days), which signals the usage condition. It does not explicitly contrast with reject or other alternatives, but the meaning is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds a critical behavioral nuance: 'Secret deliverables are decrypted only for the buyer; everyone else sees a redaction.' This role-dependent visibility is essential for the agent to understand response variability and is not captured in annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and then a concise behavioral note. No redundant words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple fetch-by-ID tool with annotations covering safety, the description provides the necessary context: it returns the quote thread and deliverables, and discloses the redaction behavior. No output schema is present, but the description hints at the response content. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter is fully documented. The description does not add any extra syntax or format details beyond what the schema already states. Baseline 3 is appropriate since the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Fetch one service quote thread with its deliverables.' It specifies a unique resource and distinguishes from the listing sibling services_list_my_quotes by focusing on a single thread. The added nuance about buyer/seller side and redaction further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a specific quote by ID, and the mention of 'Buyer or seller side' indicates it works for both roles. It does not explicitly contrast with alternatives like services_list_my_quotes, but the intent is clear enough. Missing explicit 'when not to use' guidance, hence a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds meaningful behavioral context: PII redaction policy, the full set of data returned, and the refusal behavior for non-seller orders. This goes beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff. The core action and scope are front-loaded, and the refusal condition is clearly stated. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with annotations covering safety and no output schema, the description sufficiently explains what the tool returns and its constraints. It doesn't describe error codes or exact return format, but those are minor given the tool's simplicity and 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.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for order_id, with a clear UUID description. The description adds the semantic constraint that the order must belong to this seller, which enriches the meaning of the parameter beyond the schema. This justifies a slight bump from the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'single seller-scoped order', and enumerates the included data (buyer shipping address, items, shipment, payment status, return/dispute). It also distinguishes itself from general order fetches by emphasizing seller scope and the refusal condition, which differentiates it from siblings like orders_get and seller_list_orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a single seller-scoped order and notes it refuses if not against the seller, which sets expectations. However, it does not explicitly name alternative tools or conditions for choosing between them, though the context of sibling tools (orders_get, seller_list_orders) makes the distinction inferable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately represents a read-only, paginated listing operation and clarifies the status semantics. The readOnlyHint and idempotentHint annotations already cover side-effect transparency, and the description adds useful behavioral detail without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured, packing purpose, status semantics, distinction from a sibling tool, and follow-up workflow into a few focused sentences without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides enough context for correct invocation, including pagination, status behavior, and what kind of records are listed. It does not describe the response shape, but no output schema is present and the core usage context is sufficiently covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all three parameters with descriptions. The description adds valuable semantic clarity, especially the meaning of 'active' as a combined status and the relationship between status values and the listing workflow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists seller-side sales that still require work, and explicitly contrasts it with services_list_open_requests, making its purpose unambiguous and distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit guidance on when to use this tool as the polling mechanism for fixed-price listings, explains why fixed-mode purchases do not appear in open requests, and indicates the follow-up actions (services_start_work then services_submit_deliverable).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only indicate non-read-only and non-idempotent; the description adds crucial behavioral details: acceptance window starts, re-submission restarts it, files land on object storage, secrets are envelope-encrypted and buyer-only. This significantly exceeds what annotations convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, then compactly covers kind variations, storage/encryption, and behavioral consequences. No redundant fluff; every clause adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter mutation with no output schema, the description covers the essential decision points (kind selection, file format, secret security) and workflow effects. It omits error conditions and auth prerequisites, but these are likely covered by the broader tool context and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, but the description adds meaning beyond field descriptions by explaining kind-specific handling (base64 file size limit, secret encryption, filename sanitization) and the consequence of re-submission, which the schema does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action (submit deliverable), the resource (paid/in-progress quote), and the seller-side scope. Lists the four deliverable kinds and differentiates from sibling tools like services_submit_quote (quote submission) and services_acknowledge_delivery (buyer acceptance).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly ties usage to a paid/in-progress quote and describes the acceptance-window start and revision behavior, giving clear when-to-use context. Does not name alternative tools or explicit exclusions, but the context is unambiguous enough to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful context about the default shipping address behavior in purchase_create_intent, but does not further detail side effects or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant wording, directly conveying the purpose and usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no parameters or output schema, the description fully covers what the tool does and when it should not be used, making it complete for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the baseline score of 4 applies. The mention of address_id refers to another tool's parameter and does not confuse this tool's own semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the principal's saved shipping addresses, using a specific verb and resource. It distinguishes itself from sibling tools like addresses_create and purchase_create_intent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises against calling this every purchase and points to purchase_create_intent as the alternative that uses a default address if address_id is omitted, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations are all 'false', giving little behavioral signal, so the description carries the full burden. It goes well beyond the schema by revealing that filing on a service quote pauses its payout auto-release, and that a deterministic auto-classifier routes clear-cut cases while the rest get admin review with a 72h SLA. This is exactly the meaningful behavior an agent needs to know.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: the first sentence states the action and target types, the second clarifies the target exclusivity, and the remaining sentences cover the piece side-effect and the resolution flow. No filler or redundant explanation for what the schema already states.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of six parameters, a sizeable enum, and an output schema absent, the description covers every key fact needed to invoke it correctly: target types, reason mapping, exclusivity, optionality, and critical side-effects. Combined with the schema's own field descriptions, the agent has enough to safely file a dispute.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% parameter coverage, so the baseline is 3. The description adds value by grouping reason enums into goods-only/service-only/generic categories, reinforcing the one-of-order_id-or-service_quote_id constraint, and connecting service_quote_id to a behavioral side-effect. It does not duplicate any deeper schema meaning but clarifies the cross-parameter relationships.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific verb 'File a dispute' and names both target resources: a goods order (order_id) or a service quote (service_quote_id). It distinguishes itself from dispute sibling tools by focusing on creation, and it clearly outlines the reason enums and the 'exactly one' constraint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly tells the agent when to use this tool – to initiate a dispute on either target type with the appropriate reason set. However, it does not explicitly name alternative dispute tools (e.g., disputes_respond, disputes_withdraw) or say 'not for adding evidence or withdrawing', so the agent has to infer that from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds the specific 404 behavior for role mismatch, which is an important behavioral detail not covered by annotations. No side effects are omitted; it is purely a fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundancy or filler. It front-loads the core action and includes the role/404 nuance efficiently, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description states what the response contains ('full evidence trail and timeline') and the error condition (404 for role mismatch). For a simple read operation, this is complete context; no additional information is needed to decide whether to invoke and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes dispute_id as 'UUID of the dispute to fetch' with full coverage, so the description does not add much meaning beyond echoing 'by id'. The mention of 'full evidence trail and timeline' relates to output rather than parameter semantics. Baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch' and the resource 'one dispute by id', distinguishing it from siblings like disputes_list (which fetches multiple) and disputes_file (which creates). It also specifies the full evidence trail and timeline, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Buyer-side or seller-side caller' and notes the 404 condition when the dispute does not belong to the caller's roles, providing clear guidance on when this tool is appropriate. It also implies use when needing the full evidence/timeline, which separates it from lighter list operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and idempotentHint annotations, the description adds a meaningful behavioral guarantee: full card numbers are never exposed to agents. This goes beyond the annotations and gives concrete safety expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no fluff. It front-loads the primary purpose and then adds relevant behavioral detail. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides sufficient context for the tool's purpose and behavior: it states what data is returned, the security constraint, and the relationship with purchase_confirm_intent. Given the simplicity of the operation, this is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline score is 4. The description does not need to describe parameters, and it does not add any parameter-related information. Since there are no parameters, no further explanation is required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists the principal's saved payment methods, specifies the returned data (last4 + brand), and explicitly notes that full card numbers are never exposed. This unambiguously distinguishes it from payment_methods_create and other related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context by explaining how purchase_confirm_intent defaults when no payment_method_id is passed, implying when this list might be needed. However, it does not explicitly state 'use this tool when you need to present payment methods for selection' or otherwise give direct usage conditions relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly mentions it fetches a single return and lists the response fields, plus the refusal condition, giving a clear behavioral picture. This aligns with the readOnly and idempotent annotations, and no contradictory side effects are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to cover purpose, scope, result contents, and a refusal condition without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even though there is no output schema, the description enumerates key fields in the response, so an agent knows what to expect. The input is fully described, and the refusal condition adds important context for handling edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter (return_id) has a clear description of its format (UUID) and purpose, and the tool description explains that it refers to a return on a seller-owned order. This provides sufficient meaning beyond the schema alone, though it could be slightly more explicit about the relationship to the seller context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action (fetch), the subject (a single return against a seller-owned order), and the specific information returned (reason, status, restocking fee, inspection notes, refund ledger), making its purpose unambiguous and distinct from other return-related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It states the scope (bound seller's orders) and the refusal condition (if not on a seller-owned order), which helps an agent decide when to use it. However, it does not explicitly name alternatives like 'returns_get' or 'seller_list_returns', though the context signals provide those siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful behavioral context by mentioning pagination and the seller-side view, which clarifies the expected behavior without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, then the filter example, and finally the sibling comparison. Every sentence adds value with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set and no output schema, the description provides everything needed to call the tool correctly: the purpose, the pagination behavior, the filter usage, and the relationship to orders_list. No critical information is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all three parameters with descriptions, so the baseline is 3. The description goes beyond this by explaining the status filter with an example, adding semantic meaning to how the status parameter should be used. It doesn't add context for cursor or page_size, but those are already well described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists orders for the seller's products, using the specific verb 'List' with a clear resource and scope. It also distinguishes it from the sibling orders_list by calling it the 'seller-equivalent,' so an agent can immediately tell which tool to use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly names the alternative orders_list and positions this as its seller-side counterpart. It also provides a concrete usage example ('paid_awaiting_fulfillment' to find orders that need shipping), giving clear when-to-use guidance beyond the raw parameter schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint, idempotentHint, and destructiveHint annotations already cover the safety profile. The description adds behavioral context by noting pagination and filtering, but does not explicitly state side-effect absence beyond the hints. This is sufficient given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, two sentences, and front-loads the core purpose. It avoids fluff and directly covers scope, pagination, filtering, and the sibling relationship.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with three parameters and no output schema, the description provides all necessary context: seller scope, pagination, filter options, and the relationship to returns_list. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for all three parameters. The description text adds a purpose for the status filter ('to triage what needs inspection') and reinforces the pagination behavior, which goes slightly beyond the schema without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a clear resource ('returns filed against the bound seller's orders'), and distinguishes this tool from the generic returns_list by calling it the 'Seller-equivalent of returns_list'. This makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions the use case for filtering by status ('to triage what needs inspection') and clarifies the seller-scoped context by comparing to returns_list. This gives clear guidance on when to use this tool versus its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond annotations. It reveals that this operation charges immediately, shares rails with goods purchases, can return a confirmation_required kickback with a token, requires re-acceptance after principal sign-off, and holds funds in escrow until deliverable acceptance. This is rich behavioral disclosure that the annotations (only readOnlyHint=false, etc.) do not provide. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences but packs substantial information without redundancy. It front-loads the primary action, then explains the special kickback scenario and escrow behavior. Every clause adds value, and there is no fluff. The structure is efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and complex behavior (kickbacks, escrow, delegation), the description covers the essential flow: immediate charge, potential confirmation_required retry, and escrow holding. It doesn't detail return values, but with no output schema, that is not required. The description is sufficiently complete for an agent to call it correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for all 5 parameters with descriptive text. The description adds semantic context by explaining the relationship between confirmation_token and acknowledged_confirmation, and how payment_method_id is optional with a fallback to envelope-bound card. This goes beyond the schema's individual parameter descriptions, enhancing the agent's understanding of the flow.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Accept a submitted quote and charge immediately') with a clear resource and effect. It distinguishes from sibling tools like services_purchase (which likely handles direct purchase) and services_submit_quote (which is for providers). The verb 'accept' plus the immediate charge clearly differentiates it from reject/counter flows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the primary use case: accepting a quote and initiating payment. It explicitly describes the retry flow when a confirmation_required kickback occurs, telling the agent to re-accept with acknowledged_confirmation and the token. It doesn't explicitly state alternatives, but the context (services workflow) and the mention of 'delegation caps' and 'payment-envelope rails' give enough guidance for when to use this vs. other services tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite annotations only marking readOnly=false and idempotent=false, the description discloses significant behavioral side effects: overwriting the standing offer, keeping the thread in 'quoted', restarting the buyer's SLA, and enforcing a 6-counter cap. It also clarifies that no charge is incurred yet and that caps/confirmation are re-checked at accept. This fully informs the agent of state changes and consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the action and key constraints. Every sentence adds value: the side-specific rules, the overwrite/SLA effect, the counter limit, and the charge note. There is no filler or repetition—information-dense yet concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutations, SLA reset, counter cap, side-specific permissions), the description covers all relevant execution context. It states what happens to the thread state, the count limit, and the deferred charge check. With no output schema, the description sufficiently explains the outcome and side effects an agent needs to know.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptive parameter explanations (price in pence, ETA in minutes, optional terms, UUID format). The description repeats these facts without adding new meaning beyond what the schema already conveys. Since the schema does the heavy lifting, the description contributes little extra parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Post a counter-offer on a quote thread', and immediately clarifies the key inputs (price in pence, ETA in minutes, optional terms). It explicitly distinguishes from related actions by outlining allowed conditions for buyer vs seller, making it clear it is not the accept/reject/submit-quote flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit when-to-use guidance: the buyer can counter only if haggling is enabled, the seller can always counter pre-accept. It also states the boundary condition ('Bounded to 6 counters per thread; past that, only accept or reject'), effectively steering the agent to the accept/reject tools beyond the limit. This is direct usage guidance that resolves ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the description adds meaningful behavioral details about response content (each leaf carries its JSON Schema and filterable/rangeable arrays). There is no contradiction between the description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, tightly worded, and front-loads the core purpose. Every clause adds useful information without redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description provides enough context about what is returned (taxonomy tree, leaf schemas, filterable/rangeable arrays). It also covers input semantics and scoping, so an agent has sufficient information to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter slug is fully described in the schema and in the description: it roots the listing at that node plus descendants, and omitting it returns the full tree. The meaning and optionality are both clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('marketplace's category taxonomy'), and it distinguishes this tool from siblings like catalog_search_products and catalog_describe_category by focusing on listing the taxonomy tree. It also explains the optional subtree scoping, which makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the optional slug parameter and how it roots the listing at a subtree, which is useful guidance. It does not explicitly contrast with catalog_describe_category, but the purpose is clear enough that an agent can infer when to use this list operation versus a describe operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only and idempotent; the description adds that it is a polling tool for unanswered requests, reinforcing the safe, non-destructive nature. No side effects are implied.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences conveying the essential context: seller-side, status filter, polling purpose, and recommended follow-up action. No redundant or extraneous wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the parameters are fully self-explanatory and there is no output schema, the description sufficiently states what the tool returns (a list of unanswered quote requests) and the workflow context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: cursor and page_size both have clear descriptions. The description adds no extra parameter info, but none is needed given the complete schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
States clearly it lists unanswered quote requests (status=requested) from the seller side, distinguishing it from buyer-facing tools. The mention of 'respond with services_submit_quote' further clarifies the intended purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly identifies itself as the primary polling tool for seller agents and directs the next step (respond with services_submit_quote). This clearly signals when to use this tool versus alternatives like buyer-side quote listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bitroadai/bitroad-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server