ebay-mcp

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

With no annotations provided, the description carries full burden but only describes the high-level action (accept and refund). It does not disclose side effects, reversibility, or post-action state changes, leaving significant behavioral gaps for a mutation tool.

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

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

The description is extremely concise with a single sentence for purpose followed by scope information, front-loading key information without unnecessary verbosity.

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

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

The description covers purpose and OAuth scope, but lacks details on expected response (no output schema), prerequisites beyond scope, or behavior after acceptance. Given the absence of annotations and output schema, the description is minimally adequate but could be more informative.

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

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

Schema coverage is 100%, so the input schema already documents parameters. The description adds no additional meaning beyond what is in the schema, meeting baseline requirements but providing no extra value.

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

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

The description clearly states the tool accepts a payment dispute and allows eBay to refund the buyer, specifying the action and resource. It distinguishes from siblings like ebay_contest_payment_dispute by indicating when to use this tool (when agreeing with buyer claim).

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

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

The description provides a clear usage condition ('when you agree with the buyer claim') and includes required OAuth scope, guiding the agent on when to use this tool. However, it does not explicitly name alternatives or state when not to use it beyond the condition.

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

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

With no annotations, description carries full burden. It only states action and scope, missing behavioral traits like idempotency, rate limits, or side effects. Minimal disclosure beyond basic purpose.

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

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

Description is concise and front-loaded with the action. OAuth scope is useful but might be better in annotations. No wasted words, but could be slightly more efficient.

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

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

Adequate for a tool with full schema coverage and no output schema. Lacks mention of prerequisites (e.g., upload file step) and expected response. Sufficient but not rich.

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

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

Schema coverage is 100%, so baseline 3 applies. Description does not add additional meaning beyond schema descriptions; 'evidence files and supporting information' is generic.

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

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

Description clearly states the verb 'add evidence' and context 'payment dispute', distinguishing from related tools like update and upload. However, it does not explicitly differentiate from siblings.

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

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

Provides required OAuth scope, indicating when it can be used, but lacks explicit guidance on when to use this tool versus alternatives like update or upload, and no prerequisites mentioned.

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

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

Annotations only declare readOnlyHint=false; the description goes far beyond that by disclosing the asynchronous contract, the { taskId, location } response, the required polling loop until COMPLETED/FAILED, the single-in-flight-change restriction, and the subscription/auth requirement. This is unusually complete behavioral context for a mutation tool.

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

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

Front-loaded with purpose and parameter guidance, then the async/polling workflow and constraints. Every sentence carries information, though the parameter recap and the polling instruction could be trimmed slightly given the schema already covers parameters.

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

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

With no output schema, the description compensates by describing the returned { taskId, location } and how to poll. Combined with auth and concurrency caveats, an agent has everything needed to invoke and follow up correctly.

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

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

Schema description coverage is 100%, so the schema already documents categoryName, destinationParentCategoryId (including the -999 top-level convention), and listingDestinationCategoryId. The description restates the same parameter behavior without adding new syntax or edge cases, so the baseline 3 applies.

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

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

States a specific verb and resource ('Add one custom category to the eBay Store') and ties it to the underlying addStoreCategory API. By mentioning that only one add/rename/move/delete can be in flight, it implicitly distinguishes itself from the sibling rename_store_category, move_store_category, and delete_store_category tools.

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

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

Explicitly names the alternatives for polling (ebay_get_store_task with taskId, or ebay_get_store_tasks) and the precondition (active eBay Store subscription / sell.stores scope). It also states the concurrency constraint that blocks a new change until the prior task finishes, which is exactly the when-not guidance an agent needs.

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

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

The description adds substantial behavioral detail beyond the annotation readOnlyHint=false: the read-modify-write sequence, atomicity (item left untouched on any upload failure unless allowPartial is true), per-file results in the error, the append-vs-replace behavior, and the local file access opt-in with EBAY_MCP_MEDIA_DIRS/EBAY_MCP_MEDIA_ROOT and symlink resolution. This goes far beyond what the schema and 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.

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

Two paragraphs, front-loaded with the core action, then the critical atomicity/failure behavior, then file-access constraints. Every sentence earns its place — the local access restriction is important because it was not in the schema's coverage and would otherwise cause failed calls. No filler.

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

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

This is a complex mutation tool (6 parameters, upload orchestration, partial-failure semantics, local-file access restrictions, video processing wait) but the description covers all the non-obvious operational concerns: order, atomicity, replace/append, allowPartial, local path constraints, and waitForProcessingSeconds' relation to ebay_get_video. The output schema is absent, but for attachment operations the description explains what happens on failure (per-file results in error). Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents parameters well. The description adds meaningful orchestration semantics beyond the schema: files are uploaded 'in order', the 'reading the item then rewriting only product.imageUrls and product.videoIds' behavior explains how imagePaths/videoPaths map to the item, and the failure/partial behavior for allowPartial. It does not deeply re-explain each parameter, but the schema already covers syntax; the description adds sequencing and failure semantics. Baseline for 100% coverage is 3; the added semantics justify a 4.

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

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

The description opens with a specific verb and resource: 'Upload local pictures and/or a video and attach them to an existing inventory item.' It clearly delineates the exact fields modified (product.imageUrls and product.videoIds), distinguishes append vs. replace behavior, and notes what is preserved (everything else, no offer published). This distinguishes it well from siblings like ebay_create_or_replace_inventory_item, ebay_upload_images, ebay_upload_video, ebay_get_video, and ebay_create_offer.

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

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

The description gives explicit context: use this to attach media to an existing inventory item, it appends by default, and can replace with replaceExisting. It states what the tool does not do ('no offer is published', 'Everything else on the item is preserved'), which helps an agent decide between this and update/create inventory item tools. However, it does not explicitly name sibling tools as alternatives or state when-not-to-use it (e.g., when you need to create the item itself). Clear context, but no explicit exclusions naming alternatives, so 4 rather than 5.

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

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

No annotations exist, so the description must disclose behavioral traits. It indicates a write/destructive operation ('Cancel') but provides no details on effects, reversibility, permissions, rate limits, or partial failure handling for the bulk request.

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

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

The description is a single concise sentence, but it omits essential details. It earns its place but does not provide sufficient guidance, so it is not optimally concise.

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

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

Given the lack of annotations, opaque schema, and no output schema, the description is highly incomplete. It fails to explain the input format, expected output, error conditions, or behavior, making the tool nearly unusable for an AI agent.

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

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

The sole parameter 'body' is required but has no defined properties and allows additionalProperties. Schema description coverage is 0%, and the description gives no hint about the body's structure, leaving the agent unable to construct a valid request.

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

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

The description clearly states the action 'Cancel' and resource 'multiple packages', with the context 'in one request'. It distinguishes from the singular 'ebay_cancel_package' and other bulk operations like 'ebay_bulk_confirm_packages'.

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

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

The context for use is clear: cancel multiple packages at once, implying it's an alternative to calling the single-cancel tool repeatedly. However, no explicit when-not-to-use or prerequisites are provided.

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

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

No annotations are provided, so the description must fully cover behavioral traits. It only states a vague 'confirm' without explaining side effects, state changes, authentication needs, or limitations. For a mutation tool, this is insufficient.

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

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

The description is one short sentence, which is concise but sacrifices necessary detail. It fails to earn its place by omitting critical information about the tool's usage.

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

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

Given the complex input schema with no parameter descriptions, no output schema, and the tool being a bulk mutation, the description is severely incomplete. It does not enable an agent to use the tool effectively.

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

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

The only parameter 'body' is a free-form object with schema coverage 0%. The description offers no hint about its expected structure, required fields, or format. The agent has no guidance on constructing a valid request.

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

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

The description clearly states the action ('Confirm'), the resource ('multiple packages'), and the scope ('in one request'), effectively distinguishing it from the single-package sibling 'ebay_confirm_package'.

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

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

No guidance on when to use this bulk version versus the single-package tool, no prerequisites or conditions mentioned. The description only implies usage through the name and bulk indication.

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

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

The annotation only declares readOnlyHint: false, indicating a write operation. The description adds 'create' but gives no further behavioral context: it does not mention whether the operation is idempotent, what happens to existing ads, rate limits, or the response format. For a bulk write operation with no other annotations, this is a significant transparency gap.

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

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

The description is a single, direct sentence that states the action and resource without extraneous detail. It is concise and appropriately sized for the tool's complexity.

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

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

The tool is a bulk operation with nested objects and no output schema. The description omits key contextual information: it does not mention that the request array can contain multiple items, any constraints on the number of items, whether the campaign must be active, or how errors are reported. Given the complexity and lack of annotation support, the description is incomplete for an agent to use it correctly without further investigation.

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

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

The input schema has 100% description coverage: campaignId is described as 'campaignId required endpoint parameter' and request as 'Bulk create ads by inventory reference request body'. These schema descriptions are minimal but exist. The tool description adds nothing about the parameters—it does not explain the structure of the request array or the meaning of fields like bidPercentage or inventoryReferenceType. With schema coverage at 100%, the baseline is 3, and the description does not add value beyond the schema.

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

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

The description clearly states the action (Bulk create) and the resource (ads by inventory reference). The term 'Bulk' distinguishes it from single create tools like ebay_create_ads_by_inventory_reference, and 'by inventory reference' distinguishes it from bulk create by listing ID (ebay_bulk_create_ads_by_listing_id). However, it does not explicitly compare itself to these siblings, leaving some ambiguity for an agent that must choose between them.

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

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

The description provides no guidance on when to use this tool versus the single create or the listing-ID variant. It does not state prerequisites (e.g., campaign must exist), nor any conditions under which this tool should be avoided. An agent has to infer usage from the name alone, which is insufficient given the large number of related ad tools.

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

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

The description's 'Bulk create' aligns with readOnlyHint=false and clarifies that this is a mutation that creates ads, not a read operation. However, it does not disclose additional behavioral traits such as whether the operation is asynchronous, whether partial failures occur, what side effects are produced, or any rate-limit/batch constraints. With annotations providing only a read-only flag, the description adds minimal behavioral context beyond the mutation type.

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

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

The description is a single, front-loaded sentence that contains the essential action ('Bulk create ads'), the key ('by listing id'), and the API context. There is no filler or redundant restatement of the tool name, and every word contributes to identifying the operation.

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

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

Given the tool's nested request object, the absence of an output schema, and the lack of any usage or behavioral guidance, the one-sentence description is not complete enough for an agent to confidently invoke the tool. The agent cannot tell how to structure the requests array, whether bidPercentage is required, what the relationship between adGroupId and listingId is, or what response format to expect.

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

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

Schema description coverage is 100%, so the description is not required to explain the top-level parameters. The description itself adds no parameter-level meaning: 'request' is only described as 'Bulk create ads by listing id request body' and campaignId as 'campaignId required endpoint parameter'. Nested fields like adGroupId, listingId, and bidPercentage are left entirely to the agent to infer, but the high schema coverage keeps this at baseline.

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

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

The description states a specific verb ('create'), a specific resource ('ads'), and a specific selection key ('by listing id'), which clearly distinguishes this tool from siblings like ebay_bulk_create_ads_by_inventory_reference and ebay_create_ad_by_listing_id. It also identifies the API domain ('eBay Marketing API'), leaving no ambiguity about what operation is performed.

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

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

The description does not provide any guidance about when to choose this tool over alternatives. It does not mention that single-ad creation should use ebay_create_ad_by_listing_id, or that inventory-reference-based bulk creation should use ebay_bulk_create_ads_by_inventory_reference. The 'bulk' and 'by listing id' wording implies the use case, but no explicit exclusions or alternative conditions are given.

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

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

The annotation readOnlyHint=false indicates a write operation, and the description confirms creation. However, the description adds no behavioral details beyond the annotation—no mention of side effects, rate limits, required permissions, or response behavior. The description does not contradict annotations, but it contributes minimal extra context.

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

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

The description is a single concise sentence that front-loads the action and resource. There is no extraneous text or repetition, making it efficiently structured.

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

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

This is a complex bulk operation with a nested request object, but the description provides no explanation of the inner fields (adGroupId, keywordText, matchType, bid) beyond what the schema offers. There is no output schema, so the response format is unknown. The tool would benefit from clarifying expected inputs and outcomes.

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

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

Schema description coverage is 100%, and the schema already describes the request body and campaignId. The description adds no parameter-level details. Since the schema covers all parameters, the baseline of 3 is appropriate, though the description could have clarified nested field meanings.

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

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

The description states a specific verb ('Bulk create') and resource ('keyword') through the eBay Marketing API. It is clear and distinct from single-keyword tools, though it does not explicitly name siblings like ebay_create_keyword or ebay_bulk_update_keyword. The 'bulk' qualifier provides adequate differentiation.

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

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

There is no guidance on when to use this tool versus alternatives such as ebay_create_keyword for single creation or ebay_bulk_update_keyword for updates. The description only implies bulk usage without stating prerequisites, limits, or selection criteria.

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

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

Annotations only include readOnlyHint: false, which indicates a write operation. The description adds no behavioral context beyond that—no mention of side effects, irreversibility, required authentication, rate limits, or what happens to existing keywords. Since the annotation already signals mutation, the description contributes no additional transparency.

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

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

A single sentence that is front-loaded with the core purpose. There is zero fluff, and the sentence directly conveys the action and target. It is appropriately concise for a tool with a clear function.

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

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

The tool has a nested request structure with multiple fields, yet the description offers no guidance on how to construct the request, which fields are required (the schema marks only two fields required inside each item, but adGroupId and campaignId are not required—a potentially confusing omission), or what the response contains. No output schema exists, so the agent is left without return-value expectations. Given the complexity, the description is incomplete.

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

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

Schema description coverage is 100% because the 'request' property has a description, but the individual fields (adGroupId, campaignId, negativeKeywordText, negativeKeywordMatchType) lack descriptions in the schema. The tool description does not explain any parameter semantics, such as required fields or match type options. With high schema coverage, a baseline of 3 is appropriate, but the description adds no value beyond the schema.

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

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

The description states a specific verb ('bulk create') and a clear resource ('negative keyword') and names the API context ('eBay Marketing API'). It distinguishes from sibling tools like ebay_create_negative_keyword (single create) and ebay_bulk_update_negative_keyword (update) by explicitly indicating bulk creation. This gives the agent a precise understanding of what the tool does without needing to open the schema.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention that it should be used for creating multiple negative keywords at once, nor does it explain when to prefer the single-create variant (ebay_create_negative_keyword). The 'bulk' prefix implies multi-item usage, but no direct statement of context or exclusions is provided.

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

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

With no annotations, the description carries the full behavioral disclosure burden. It goes beyond the schema by warning that listingStartDate can incur a fee, stating that mixed-format bodies are rejected before any eBay request, and clarifying format-specific restrictions like no per-buyer limit or eBay Plus for auctions. It does not cover partial-failure behavior or rate limits, but it is substantially informative.

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

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

The description is dense but every sentence carries rule content; there is no filler. It is front-loaded with the core purpose and max limit, then details format-specific rules and a fee warning. It could be more scannable, but the length is justified by the complexity of the supported offer formats.

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

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

Given the complex nested schema and absence of both annotations and output schema, the description covers the critical decisions: format selection, pricing fields, listing duration, quantity, Best Offer, eBay Plus, and scheduling. Missing details like partial-failure semantics or behavior when exceeding 25 offers are not addressed, but the description is strong enough for an agent to invoke the tool with correct intent.

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

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

Schema coverage is effectively 0% for the top-level parameter, and the description compensates extensively. It maps FIXED_PRICE vs AUCTION formats to their required and optional fields, adds cross-field constraints like the 30% Buy It Now margin and incompatibility with Best Offer, and clarifies auction-specific rules such as availableQuantity omitted or 1. This is far more semantically useful than the raw schema.

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

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

The description opens with a specific verb and resource: 'Bulk create up to 25 offers in one request.' It clearly distinguishes this tool from ebay_create_offer by emphasizing the bulk aspect and immediately scoping the operation to a maximum of 25 offers.

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

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

The description gives clear context for when to use the tool — bulk offer creation — and states that each request must follow ebay_create_offer rules. It does not explicitly name alternatives or exclusion conditions, such as 'use ebay_create_offer for a single offer,' but the bulk framing and detailed constraints make the intended usage clear.

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

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

With no annotations, the description carries full burden but reveals only that the tool performs a mutation (create/replace). Key behavioral traits like idempotency, limits, authentication needs, or error conditions are omitted.

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

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

The description is a single, front-loaded sentence with no redundancy. It is concise but at the cost of missing essential details, balancing brevity and information.

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

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

For a tool with one parameter and no output schema or annotations, the description is insufficient. It does not explain the request body structure, return value, or operational context, leaving agents with significant gaps.

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

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

The single parameter 'body' has a generic description ('Generated BulkInventoryItem request body') that adds no structural or semantic details. Despite 100% schema coverage, the description fails to explain what the body should contain.

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

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

The description clearly states the action (bulk create or replace) and resource (inventory items), distinguishing it from singular alternatives via the word 'bulk'. However, it could be more specific about what 'multiple' entails.

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

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

No guidance is provided on when to use this tool versus sibling tools like ebay_create_or_replace_inventory_item or other bulk operations. Prerequisites, constraints, and alternatives are absent.

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

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

Annotations already indicate a non-read-only, idempotent operation, so the description's job is to add behavioral nuance beyond that. The description simply restates the tool name and provides no details on replacement semantics, partial failure behavior, atomicity, or validation. It adds little to what annotations and the name already convey.

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

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

The description is a single, clear sentence with no filler. It front-loads the core action and resource, even though it closely mirrors the tool name. It is appropriately minimal for the simple parameter structure.

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

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

For a bulk mutation tool with no output schema, the description is too sparse. It does not explain what "replace" means for existing sales tax tables, whether the operation is atomic or per-request, or what failure modes exist. An agent would need additional context to use it confidently beyond what the name and schema provide.

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

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

Schema coverage is 100%, so the schema fully documents the requests parameter and its nested structure. The description adds nothing beyond the schema about parameters, which aligns with the baseline of 3 when the schema carries the heavy lifting.

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

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

The description states a specific action (bulk create or replace) on a specific resource (sales tax tables), clearly distinguishing it from singular, delete, and get siblings such as ebay_create_or_replace_sales_tax, ebay_delete_sales_tax, and ebay_get_sales_tax. An agent can immediately understand the tool's scope and function without opening the schema.

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

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

The word "Bulk" implies use for multiple tax tables, but the description does not explicitly state when to use this tool versus the singular ebay_create_or_replace_sales_tax or other tax-related tools. There are no exclusions or alternative routing hints, leaving the agent to infer usage context from the name alone.

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

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

The description merely restates the action and API, adding no behavioral context beyond the readOnlyHint=false annotation. It does not disclose side effects, irreversibility, rate limits, or error behavior, which matters for a mutating bulk operation.

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

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

The description is a single sentence with no fluff, but it essentially restates the tool name with the API context added. It is efficient but adds little informational value beyond the name.

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

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

For a mutation tool with a nested request body and no output schema, the description is too thin. It omits constraints on request count, response format, and failure behavior, leaving gaps for an agent trying to invoke the tool correctly.

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

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

Schema description coverage is 100% for top-level parameters, so the baseline is 3. The parameter descriptions are largely tautological (e.g., 'campaignId required endpoint parameter') and the tool description adds no further meaning to the schema, so the score stays at baseline.

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

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

The description states a specific verb ('Bulk delete'), resource ('ads'), and the key qualifier ('by inventory reference'), which clearly differentiates it from siblings like ebay_bulk_delete_ads_by_listing_id. It does not explicitly name the sibling singular variant ebay_delete_ads_by_inventory_reference, but the word 'Bulk' covers that distinction, making the purpose evident.

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

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

The description provides no guidance on when to choose this tool over alternatives such as the non-bulk delete or the bulk delete by listing ID. It neither states conditions for use nor exclusions, leaving the agent to infer when it is appropriate.

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

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

The annotations only provide readOnlyHint=false, so the description carries responsibility for behavioral disclosure. 'Bulk delete' implies mutation, but there is no mention of permanence, whether the operation is atomic, or how success/failure is reported. The description adds almost nothing beyond what the verb 'delete' and the tool name already imply.

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

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

A single sentence with the action and resource front-loaded. 'Through the eBay Marketing API' is slightly redundant given the ebay_ prefix, but it is minor. The description is appropriately concise and readable.

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

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

This tool has a nested request object and no output schema, yet the description does not explain how to populate request.requests[].adId or how campaignId relates to the operation. The listing-id versus adId ambiguity could lead an agent to construct an invalid call. Overall, the description is insufficient for correct invocation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds no meaningful parameter detail beyond the schema, and it may even mislead by saying 'by listing id' while the request schema requires adId. The schema's own descriptions are low-value, but full coverage keeps this at the baseline.

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

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

The description states a specific action ('Bulk delete ads') and resource ('ads by listing id'), which broadly distinguishes it from deletion by inventory reference. However, the phrase 'by listing id' conflicts with the schema's adId property, creating ambiguity about which identifier is actually used. The core purpose is still understandable but slightly imprecise.

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

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

No guidance is given on when to use this tool instead of alternatives like ebay_delete_ad or ebay_bulk_delete_ads_by_inventory_reference. The description states only the operation itself, with no prerequisites, exclusions, or decision criteria. Any usage context must be inferred from the tool name alone.

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

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

The description states 'Delete', implying a destructive action, but provides no details on side effects, reversibility, or required permissions. With no annotations, this minimal disclosure is insufficient for safe invocation.

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

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

The description is concise (one sentence), but overly terse. It sacrifices necessary detail for brevity, making it minimally adequate but not well-structured.

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

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

Given the complexity of a bulk delete operation, the description lacks essential context such as maximum package count, identifier format, and output expectations. The high number of siblings increases the need for clarity, which is absent.

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

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

The single parameter 'body' is an untyped object with additionalProperties true, and the description adds zero information about its expected structure. With 0% schema coverage, the description fails to help the agent construct valid input.

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

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

The description 'Delete multiple packages in one request' clearly identifies the tool's action (delete) and resource (multiple packages), distinguishing its bulk nature from single-package operations like ebay_delete_package.

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

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

No guidance is provided on when to use this tool versus alternatives such as ebay_delete_package (single) or ebay_bulk_cancel_packages. The description lacks context for choosing between similar operations.

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

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

Without annotations, the description carries no behavioral details (e.g., read-only, permissions, rate limits). It only repeats the name, leaving the agent uninformed about side effects or requirements.

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

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

The description is a single concise sentence with no wasted words, though it could benefit from slightly more structure to include key context.

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

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

Given the lack of output schema and annotations, the brief description is insufficient. It does not explain how to use the body parameter, expected input/output, or any operational details.

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

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

Schema coverage is 100% with a single 'body' parameter described as 'Generated BulkGetInventoryItem request body'. The tool description adds no additional meaning beyond the schema, meeting the baseline for high coverage.

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

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

The description clearly states the action ('get') and resource ('inventory items') with a bulk scope, distinguishing it from single-item get or create operations among siblings.

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

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

No guidance is provided on when to use this tool versus alternatives like ebay_get_inventory_item or bulk creation. No when-not-to-use or context is given.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure, but it only states 'bulk migrate'. It does not mention whether original listings are modified or deleted, if the operation is synchronous, or any error handling behavior.

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

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

At six words, the description is extremely concise but omits critical information. It prioritizes brevity over clarity, resulting in under-specification.

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

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

Given no annotations, no output schema, and a single undocumented parameter, the description is severely incomplete for a bulk migration operation. Users need details on prerequisites, side effects, and the structure of the request body.

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

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

The schema coverage is 100% with one parameter 'body', but the description merely repeats the parameter name as 'Generated BulkMigrateListing request body', adding no semantic detail beyond the schema. The agent gains no insight into what the body should contain.

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

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

The description uses the verb 'migrate' and specifies the resource 'listings to the inventory model', which clearly indicates the tool's action and distinguishes it from create/revise/end listing tools. However, 'migrate' could be more explicit about the conversion process.

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

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

There is no guidance on when to use this tool versus alternatives like ebay_create_listing or ebay_revise_listing. No prerequisites or scenarios are described, leaving the agent to infer usage context.

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

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

No annotations are provided, so the description must convey behavioral traits. It only says 'Bulk publish multiple offers' without disclosing whether the operation is idempotent, how partial failures are handled, rate limits, or authentication requirements.

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

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

The description is a single concise sentence with no fluff. However, a slight expansion to cover key behavioral aspects would improve clarity without sacrificing conciseness.

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

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

Given that this is a bulk operation with no output schema and no annotations, the description is incomplete. It fails to explain the return value, error handling, or how results are reported, which is critical for such a tool.

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

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

The single parameter 'body' has a schema description 'Generated BulkOffer request body', but the tool description adds no further semantic context, such as required format or constraints. The description does not help an agent understand what constitutes a valid BulkOffer request.

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

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

Description states 'Bulk publish multiple offers', clearly indicating the verb (publish) and resource (offers) with a bulk modifier that distinguishes it from the sibling ebay_publish_offer. However, it lacks specificity about the scope or nature of the bulk operation.

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

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

No guidance on when to use this tool versus alternatives like ebay_publish_offer or ebay_create_offer. There are no usage examples, prerequisites, or exclusion criteria provided.

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

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

The annotation readOnlyHint=false already conveys that this is a mutating operation. The description adds no additional behavioral context such as permissions required, idempotency, partial failure behavior, or effects on existing ads. For a mutation tool without a destructiveHint annotation, more disclosure is needed.

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

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

A single, front-loaded sentence with no filler. It communicates the core operation immediately, and the trailing 'through the eBay Marketing API' adds minimal but acceptable context.

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

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

The definition is too thin for a bulk mutation tool with nested request objects and no output schema. It omits expected values for bidPercentage, valid inventoryReferenceType options, and behavioral outcomes. An agent would likely need external API knowledge to invoke it correctly.

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

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

Schema description coverage for the two top-level parameters is 100%, so the baseline is 3. The description does not add meaning beyond the schema, and nested fields like inventoryReferenceType and bidPercentage lack value format or allowed-value explanation, but the schema already names them clearly.

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

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

The description states a specific verb ('bulk update'), resource ('ads bid'), and identifier type ('by inventory reference'). This clearly distinguishes it from sibling tools like ebay_bulk_update_ads_bid_by_listing_id and related inventory-reference bulk operations.

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

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

No guidance is provided about when to use this tool instead of alternatives such as ebay_bulk_update_ads_bid_by_listing_id, ebay_update_bid, or ebay_bulk_create_ads_by_inventory_reference. The description implies the operation but does not state context, prerequisites, or exclusions.

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

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

Annotations already declare readOnlyHint=false, so the write nature is known. The description adds no behavioral details beyond 'update' – no mention of overwriting behavior, rate limits, required scopes, or effects on existing bids. With only one annotation present, the description does not meaningfully increase transparency.

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

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

The description is a single efficient sentence that front-loads the action and scope. No filler or repetition, but the phrase 'through the eBay Marketing API' is arguably redundant given the tool name already starts with 'ebay'. Minor waste, but very concise overall.

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

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

For a bulk operation with a nested request array and no output schema, the description is too sparse. It does not explain the role of adGroupId, the format of bidPercentage (e.g., string representing a percentage), whether listingId refers to an eBay listing ID vs. inventory reference, or any batching limits. The sibling list shows many similar tools, and without more contextual detail, an agent could easily misuse the parameters.

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

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

Schema description coverage is 100% for the top-level parameters (campaignId and request), so the description does not need to repeat them. However, the nested properties inside 'requests' (adGroupId, listingId, bidPercentage) have no individual descriptions, and the tool description offers no extra semantic hints about formats or relationships beyond the schema's basic labels.

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

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

The description states a specific verb ('Bulk update') and resource ('ads bid') with a clear scope ('by listing id'), which directly distinguishes it from sibling tools like ebay_bulk_update_ads_bid_by_inventory_reference and ebay_bulk_update_ads_status_by_listing_id. It precisely conveys what the tool does.

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

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

No guidance is provided on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or scenarios that favor this tool over the many related bulk update/delete tools. The phrase 'through the eBay Marketing API' is context but not usage guidance.

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

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

The annotations provide readOnlyHint=false, indicating a write operation, and the description consistently says 'update'. However, it adds no further behavioral detail such as required permissions, side effects on existing data, rate limits, or response characteristics.

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

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

The description is a single, concise sentence with no unnecessary words. It is front-loaded with the key action and resource, though it is brief to the point of being vague on details.

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

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

Given the nested request object and no output schema, the description is minimal. It does not explain valid adStatus values, the structure of the request array, or how this tool differs from similar bulk update tools. The lack of context makes it incomplete for correct invocation.

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

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

Schema description coverage is 100% as both campaignId and request have descriptions. The tool description adds no additional parameter meaning beyond the schema, so it meets the baseline of 3.

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

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

The description states the verb 'update' and the resource 'ads status' and mentions the eBay Marketing API. It is clear what the tool does, but it does not distinguish from the sibling tool 'ebay_bulk_update_ads_status_by_listing_id' which appears nearly identical, so it lacks differentiation.

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

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

The description gives no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or exclusions, leaving the agent to infer usage context from the name alone.

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

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

Annotations only indicate readOnlyHint=false, so the description carries the burden of behavioral disclosure. It doesn't mention potential side effects (e.g., whether ads are deactivated or reactivated), required permissions, rate limits, or failure behavior. The description adds no behavioral context beyond the fact that it updates status.

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

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

The description is a single sentence with no wasted words, so it is concise. However, it is under-specified for a tool with a nested request structure, omitting important operational details. Conciseness itself is fine, but the balance between brevity and completeness is poor.

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

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

For a bulk operation with a nested array of updates, the description is incomplete. It lacks details on the format of adStatus, whether the operation is atomic, what the response contains, and error handling. No output schema exists, so the description should clarify expected outcomes, but it does not.

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

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

The schema provides descriptions for both parameters, but they are tautological ('campaignId required endpoint parameter' and 'Bulk update ads status by listing id request body'). The nested request object's adStatus and listingId fields lack any semantic detail, such as allowed values for adStatus or the format of listingId. The description does not compensate for these gaps.

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

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

The description clearly states the verb ('update'), resource ('ads'), and scope ('by listing id'), which is specific enough to distinguish it from many siblings. It names the operation and the identifier type, though it doesn't explicitly contrast with ebay_bulk_update_ads_status or by inventory reference.

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

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

No guidance on when to use this tool versus alternatives like ebay_bulk_update_ads_status or ebay_bulk_update_ads_bid_by_listing_id. The description implies you should use it when you have listing IDs, but it doesn't say so explicitly or mention any exclusions or prerequisites.

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

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

No annotations are provided, so the description must fully disclose behavior. It states that status is set for each conversationId but omits important details like whether the operation is atomic, how partial failures are handled, what the response looks like, or if other fields are affected.

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

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

Two concise sentences with no wasted words. Essential information is front-loaded: the purpose and the status options.

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

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

For a bulk update tool with no output schema and no annotations, the description lacks completeness on error handling, response format, and behavior. While the core function is clear, critical operational context is missing.

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

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

Schema coverage is 100% with nested parameter descriptions. The description adds minor clarity (e.g., each entry sets status) but largely duplicates schema information. No additional semantics beyond what the schema provides.

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

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

The description clearly states 'Bulk update multiple conversations' with specific verb and resource. It lists the possible statuses (ACTIVE, ARCHIVE, DELETE, READ, UNREAD) and distinguishes from the sibling single-update tool 'ebay_update_conversation' by its bulk nature.

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

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

The description implies use for bulk updates but does not explicitly state when to use this over alternatives like 'ebay_update_conversation'. No guidance on when not to use or prerequisites is provided.

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

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

Annotations only provide readOnlyHint=false, which aligns with the mutating nature of 'update' but adds little. The description does not disclose whether the update replaces the entire keyword object, whether bid and keywordStatus are independently updatable, whether partial failures occur, or what the response contains.

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

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

The description is a single, front-loaded sentence with no filler or repeated structured data. It is concise, though 'through the eBay Marketing API' is somewhat redundant given the tool name and adds little value.

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

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

For a mutating tool with no output schema and sparse annotations, this description is incomplete. It does not explain what campaignId/request mean behaviorally, what keywordStatus values are valid, whether campaign state matters, or when to prefer this over ebay_update_keyword. The schema alone provides only minimal context.

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

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

Schema description coverage is 100%, so the parameter names and top-level descriptions already carry most of the load. The tool description adds no additional parameter information, and nested fields like keywordStatus, bid.value, and bid.currency lack explanatory detail, but the schema baseline of 3 is appropriate.

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

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

The description states a concrete action ('bulk update') and a specific resource ('keyword'), so an agent can tell it performs bulk keyword modification. However, it does not explicitly distinguish itself from close siblings like ebay_update_keyword or ebay_bulk_create_keyword, and it omits which keyword attributes can be updated.

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

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

There is no guidance on when to use this tool versus alternatives such as ebay_update_keyword for a single keyword or ebay_bulk_create_keyword for creation. The word 'bulk' implies multiple updates, but the description never states this selection criterion or any exclusions.

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

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

Annotations only include readOnlyHint: false, which signals this is a write operation. The description adds no behavioral context beyond that: no mention of idempotency, partial failure behavior, rate limits, required auth scopes, or what happens to existing negative keywords. For a mutation tool with minimal annotation coverage, the description carries the burden and doesn't disclose anything beyond the basic action.

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

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

The description is a single sentence, concise and front-loaded with the action. It wastes no words, though it could add a bit more context without becoming verbose. It's appropriately sized for a simple tool.

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

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

The tool has a nested request object with two fields, no output schema, and minimal annotations. The description doesn't explain what negativeKeywordStatus values are valid, whether the update is partial or full replacement, or what the response contains. Given the complexity of a bulk operation with nested objects, the description is too thin to fully guide an agent.

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

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

Schema description coverage is 100% (the 'request' property has a description 'Bulk update negative keyword request body'), so the schema already documents the top-level parameter. The description adds no meaning beyond the schema, and the nested properties (negativeKeywordId, negativeKeywordStatus) are not explained in either the schema or the description. Baseline 3 is appropriate since the schema covers the parameter name but not the nested semantics.

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

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

The description states a specific verb ('Bulk update') and resource ('negative keyword') via the eBay Marketing API. It clearly identifies the operation and resource, and the 'bulk' qualifier distinguishes it from the sibling ebay_update_negative_keyword. However, it doesn't elaborate on what fields can be updated or the effect, so it's clear but not maximally informative.

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

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

No guidance is provided on when to use this tool versus alternatives. The sibling list includes ebay_update_negative_keyword, ebay_bulk_create_negative_keyword, and ebay_create_negative_keyword, but the description doesn't mention them or specify conditions for choosing this bulk update over the single update. The 'Bulk' prefix implies usage for multiple items, but that's left to inference.

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

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

With no annotations, the description should fully disclose behavior. It only hints at updating price/quantity but omits critical details like authentication requirements, data limits, or error handling.

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

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

The description is a single sentence, efficient and front-loaded. However, it could be more informative without sacrificing conciseness.

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

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

Given the tool's single complex parameter (request body) and lack of annotations or output schema, the description is insufficient. It does not explain the 'bulk' aspect or input format.

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

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

The description adds no meaning beyond the schema's vague 'Generated BulkPriceQuantity request body'. It does not explain the structure or contents of the 'body' parameter.

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

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

The description clearly states the action ('Bulk update') and the resource ('price and quantity for multiple offers'), distinguishing it from sibling tools like ebay_update_offer (individual) or ebay_bulk_create_offer (create).

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

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

The description provides no guidance on when to use this tool versus alternatives like individual updates or when prerequisites are needed. It only states the action without context.

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

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

The description implies a mutation (cancel) but does not disclose behavioral traits like side effects, authorization requirements, or irreversibility. No annotations exist to compensate, so the description carries the full burden and falls short.

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

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

The description is a single, concise sentence that front-loads the action and key input. It is appropriately short, but could include more details without being verbose.

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

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

For a cancellation tool with one parameter and no output schema, the description should mention prerequisites, expected effects, and return behavior. It does not, leaving significant gaps for an AI agent to safely use the tool.

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

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

With 0% schema description coverage, the description must add meaning to the single parameter 'bundleId'. It merely restates 'by ID', adding no semantic value. The parameter type and format remain unclear.

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

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

The description 'Cancel a bundle by ID' clearly states the action (cancel) and resource (bundle). It distinguishes from sibling tools like ebay_cancel_package by specifying 'bundle' rather than 'package', but could be clearer about what 'bundle' means in context (e.g., shipping bundle or order bundle).

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

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

No guidance is provided on when to use this tool versus alternatives like ebay_bulk_cancel_packages or when cancellation is appropriate. The description lacks prerequisites, such as whether the bundle must be in a cancellable state.

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

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

With no annotations, the description should disclose side effects, permissions, or state changes. It only says 'Cancel', leaving behavioral traits entirely ambiguous.

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

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

The description is one concise sentence with no filler. It is appropriately short for a simple operation, though it could include more detail without losing conciseness.

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

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

Given the complexity of eBay package operations and numerous sibling tools, this description is too minimal. It lacks information about return values, success criteria, or effects on related entities.

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

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

The single parameter 'packageId' has no description in the schema (0% coverage). The tool description adds no meaning beyond the parameter name, failing to explain what the ID refers to.

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

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

The description clearly states the verb 'Cancel' and the resource 'package', making the action obvious. However, it does not differentiate from similar tools like ebay_delete_package or ebay_clone_package.

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

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

No guidance on when to use this tool versus alternatives (e.g., ebay_delete_package, ebay_bulk_cancel_packages). No prerequisites or context provided.

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

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

Beyond the destructive/readOnly annotations, the description discloses the refund side effect (totalShippingCost to billing agreement), label deletion, the failure condition once the label is used, the return content, and the special OAuth scope requirement. This is rich behavioral context that an agent cannot infer from structured fields alone.

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

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

Front-loads the core action and its effects before the operational/eligibility boilerplate, so the essential meaning lands first. The trailing scope and re-consent details are somewhat verbose but genuinely relevant for a limited-release API.

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

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

Covers action, side effects, failure condition, return value, and auth/eligibility constraints, which is everything an agent needs for a single-parameter destructive tool with no output schema. Nothing material is left unexplained.

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

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

Schema description coverage is 100% and the sole parameter (shipmentId) is fully documented in the schema. The description adds no further syntax or format detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Cancel a shipment and delete its shipping label') and names the underlying API operation (Logistics API cancelShipment). The scope is clearly shipment-level, distinguishing it in spirit from package-level siblings like ebay_cancel_package, though it never explicitly contrasts with them.

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

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

Provides one useful precondition ('Fails once the label has been used') and the eligibility restriction (limited release), which implies when the tool is usable. However, it gives no explicit guidance on when to choose this over alternatives like ebay_cancel_package or ebay_bulk_cancel_packages.

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

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

The description discloses the main behavioral impact: clearing tokens and requiring re-authentication. Since no annotations are provided, the description carries the full burden, and it adequately explains the destructive nature without contradictions.

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

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

Two concise sentences, no wasted words. The most important information is front-loaded, and every word contributes to understanding.

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

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

Given the simplicity (no parameters, no output schema), the description covers the essential effect and outcome. It could mention if any permissions are required, but for a clear operation, it is adequately complete.

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

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

With zero parameters, the baseline is 4. The description adds meaning beyond the empty schema by explaining what tokens are cleared and the consequence, which is sufficient.

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

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

The description clearly states the specific action ('Clear all stored OAuth tokens') and includes both user tokens and client credentials, distinguishing it from other sibling tools like ebay_set_user_tokens or ebay_get_token_status.

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

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

No guidance is provided on when to use this tool versus alternatives. Sibling tools like ebay_set_user_tokens or ebay_refresh_access_token exist, but the description does not explain scenarios that would favor one over the other.

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

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

Annotations only communicate readOnlyHint=false, so the description carries the burden of disclosing behavioral traits. It does not explain that cloning likely creates a new campaign, what gets copied, whether the clone is immediately active, or what the outcome is. The phrase 'through the eBay Marketing API' adds no behavioral transparency.

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

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

The description is a single, front-loaded sentence with no filler words. It is appropriately short, though it sacrifices useful context for brevity.

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

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

Given the nested request object, sparse annotations, and no output schema, the one-line description is incomplete. It does not explain the cloning semantics, what the response contains, or any constraints on campaignId and request fields, leaving an agent to rely on schema names and assumptions.

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

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

Schema coverage is 100%, so the baseline is 3 even though the description itself adds no parameter semantics. The schema descriptions are tautological ('campaignId required endpoint parameter', 'Clone campaign request body') and do not clarify what values should be provided, but the high coverage prevents a lower score.

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

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

The description states a specific verb and resource: 'Clone campaign through the eBay Marketing API.' This is a clear operation and is distinct in intent from nearby campaign tools like create_campaign or update_campaign_identification. However, it does not explicitly differentiate itself from other campaign-related siblings.

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

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

The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The only usage signal is inferred from the verb 'clone,' which is not enough for an agent to distinguish it from similarly named or related campaign mutation tools.

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

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

No annotations provided, and the description does not disclose behavioral traits such as what fields are duplicated, whether the operation is destructive or reversible, or any side effects. The phrase 'create a duplicate' is vague without additional context.

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

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

The description is extremely short (6 words) but lacks necessary detail. Conciseness should not sacrifice clarity; here it is under-specified and fails to provide value beyond a tautology of the tool name.

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

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

With many related package tools and no output schema, the description fails to explain what a 'package' is in this context, what the result looks like, or how it differs from other operations. It is not complete enough for effective tool selection.

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

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

Schema coverage is 0% and the description provides no explanation for the 'packageId' parameter. The agent has no way to know what value to provide or how it identifies the package to clone.

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

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

The description uses a specific verb 'clone' and resource 'package', clearly indicating it creates a duplicate. It distinguishes from sibling tools like 'create_package' or 'get_package' by using 'clone' rather than 'create', though it does not elaborate on what 'clone' entails.

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

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

No guidance on when to use this tool vs alternatives like 'create_package' or 'get_package'. The description does not specify context, prerequisites, or exclusions, making it difficult for an agent to decide appropriately.

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

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

No annotations provided, and description does not disclose behavioral traits like state changes, irreversibility, or required permissions. 'Confirm' implies a mutation, but effects are unexplained.

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

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

Extremely short (5 words) but under-specified. Lacks essential details, making it insufficient rather than concise.

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

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

Tool has one parameter, no output schema, and no annotations. Description is too minimal to be complete—missing side effects, return values, and prerequisites.

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

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

Single parameter 'packageId' has 0% schema description coverage, and the description does not clarify its meaning, format, or how to obtain it.

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

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

Description clearly states 'Confirm a package for shipping', giving a specific verb and resource. However, it does not differentiate from sibling tools like 'ebay_bulk_confirm_packages' or 'ebay_create_package'.

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

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

No guidance on when to use this tool vs alternatives, such as prerequisites (package must exist, state requirements) or 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.

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

Annotations are absent, so the description carries the burden. It specifies OAuth scopes required, which is helpful. However, it does not disclose behavioral traits such as whether the action is synchronous, side effects, or expected response. Partial coverage.

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

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

The description is concise with two sentences plus OAuth scope. It is well-structured and front-loaded with purpose. No wasted words.

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

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

For a simple action with 2 parameters and no output schema, the description covers the essential 'when' and OAuth. However, it lacks details on what happens after contesting, expected response, or prerequisites beyond OAuth. Slightly incomplete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions. It does not elaborate on how to use parameters effectively (e.g., how to obtain revision number).

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

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

The description clearly states the action ('Contest a payment dispute by providing evidence') and when to use it ('when you disagree with the buyer claim'). It distinguishes from sibling tools like ebay_accept_payment_dispute and ebay_get_payment_dispute.

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

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

The description provides explicit guidance on when to use ('when you disagree with the buyer claim and want to provide proof'). It implies when not to use (if agreeing, use accept_payment_dispute). However, it lacks explicit alternatives or exclusions.

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

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

No annotations were provided, so the description carries full burden. It discloses supported input formats and output type (Unix timestamp in milliseconds), but omits error handling, timezone handling, or edge cases. For a simple conversion tool, this is acceptable but slightly incomplete.

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

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

Two concise sentences with no wasted words. The description is front-loaded with the core purpose and quickly provides additional context.

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

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

Given the tool's simplicity (single parameter, no output schema), the description covers the essential aspects: purpose, supported input formats, and use case. It could mention that the return value is a number, but that is implied by 'Unix timestamp (milliseconds)'.

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

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

The only parameter 'dateInput' is fully described in the schema with 100% coverage. The description adds no additional meaning beyond the schema's description. Baseline score of 3 is appropriate.

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

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

The description clearly states 'Convert a date string or number to Unix timestamp (milliseconds)' with specific supported formats (ISO 8601, Unix timestamps, relative time). This sharply distinguishes it from all sibling tools, which are eBay operations unrelated to date conversion.

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

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

The description explicitly mentions 'Useful when setting token expiry times from user input', providing clear context for when to use this tool. While it doesn't list alternatives or when not to use it, the sibling tools are all eBay-specific, 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.

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

Annotations only provide readOnlyHint=false, which signals mutation but nothing else. The description does not disclose whether this creates a new ad, overwrites an existing ad, requires a campaign to be active, or what happens on duplicate listing IDs. It also does not mention any prerequisites like an opted-in program or existing ad group. For a mutation tool with minimal annotation coverage, the description carries the burden and does not meet it.

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

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

The description is a single sentence with no filler. It front-loads the action and resource. It could add a bit more context about prerequisites or behavior without becoming bloated, but as written it is efficient.

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

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

For a mutation tool with no output schema and minimal annotations, the description is too thin. It does not explain the expected effect, prerequisites (e.g., campaign/ad group existence, eligibility), or how it differs from the many sibling ad-creation tools. An agent would need to inspect the schema and possibly the API docs to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents campaignId and the request body. The description adds no parameter-level meaning beyond the schema, but the baseline of 3 applies because the schema does the heavy lifting. The nested request object's fields (adGroupId, listingId, bidPercentage) are self-descriptive in name but lack format details such as whether bidPercentage is a string percentage or decimal.

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

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

The description states a specific verb ('Create') and resource ('ad by listing id') and names the API ('eBay Marketing API'). It is clear enough to distinguish from bulk variants like ebay_bulk_create_ads_by_listing_id and from ebay_create_ads_by_inventory_reference, though it does not explicitly name those siblings.

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

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

The description implies this is the single-ad creation path by listing ID, and the sibling list shows bulk alternatives, but it does not explicitly state when to use this tool versus ebay_bulk_create_ads_by_listing_id or ebay_create_ads_by_inventory_reference. An agent can infer the usage context from the name and schema, but there is no direct guidance.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states 'Create', implying mutation, but does not disclose required permissions, side effects, idempotency, or expected behavior. This is insufficient for safe invocation.

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

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

The description is very concise (one sentence), which is good for readability, but it lacks essential details. It is front-loaded with the purpose, but the brevity comes at the cost of completeness.

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

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

Given the lack of annotations, output schema, and parameter details, the description is far from complete. An agent cannot infer the required body structure, response format, or potential errors, making successful invocation unlikely.

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

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

The input schema has a single parameter 'body' with no defined properties (additionalProperties: true) and 0% schema coverage. The description does not add any information about the structure or required fields of the body, leaving the agent without guidance.

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

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

The description clearly states the verb 'Create' and the resource 'address preference', and specifies the scope 'for international shipping'. It distinguishes from siblings like 'get_address_preferences' by indicating a write operation. However, the term 'address preference' is not further explained, which may cause ambiguity.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'ebay_get_address_preferences' or other creation tools. There is no mention of prerequisites, context, or 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.

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

Annotations only include readOnlyHint=false, so the description carries the burden of behavioral disclosure. It states the operation is a creation, but does not mention whether the campaign must already exist, whether the operation is idempotent, what side effects occur, or what the response contains. No behavioral details beyond the bare "Create" are provided.

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

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

The description is a single sentence with no filler or redundant phrases. It is efficiently front-loaded, though the phrase "through the eBay Marketing API" adds little value beyond what the tool name already implies.

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

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

The tool is relatively simple with only two parameters and full schema coverage, but there is no output schema and the description does not mention return values, prerequisites, or the fact that the ad group is created within the campaign identified by campaignId. It is minimally viable but leaves the agent to infer campaign-level behavior.

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

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

Schema description coverage is 100%: campaignId and request both have descriptions, and the request schema marks name as required and documents defaultBid. The description itself adds no parameter semantics, but the schema already covers the inputs, so the baseline 3 applies.

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

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

The description uses a specific verb and resource: "Create ad group", which clearly distinguishes it from sibling tools like ebay_get_ad_group, ebay_update_ad_group, and ebay_delete_campaign. It does not, however, explain what an ad group is or its relationship to a campaign, so the purpose is clear but thin.

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

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

The description gives no guidance on when to use this tool versus alternatives, no prerequisites, and no context such as "use this to add an ad group to an existing campaign." The verb "Create" implies usage only by default, but no explicit or implicit context is provided.

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

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

Annotations only provide readOnlyHint=false, which signals a write operation. The description adds no behavioral context beyond that: no mention of side effects, required permissions, rate limits, or what happens to existing ads. For a mutation tool, this is a significant gap.

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

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

The description is a single, efficient sentence that conveys the core action and resource. It's appropriately sized, though it could be more informative without becoming verbose.

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

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

For a mutation tool with no output schema and minimal annotations, the description is thin. It doesn't explain the request body structure, the meaning of bidPercentage, or how this differs from the bulk variant. An agent would need to open the schema and infer a lot.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds no additional meaning beyond what the schema provides, so the baseline 3 is appropriate.

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

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

The description states a specific verb ('Create') and resource ('ads by inventory reference') through the eBay Marketing API. It clearly distinguishes from sibling tools like ebay_create_ad_by_listing_id and ebay_bulk_create_ads_by_inventory_reference, though it doesn't explicitly name them.

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

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

The description implies usage context by naming the API and the resource type, but it doesn't explicitly state when to use this tool versus alternatives like ebay_bulk_create_ads_by_inventory_reference or ebay_create_ad_by_listing_id. An agent would need to infer the distinction from the name alone.

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

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

No annotations are provided, so the description carries full burden. It only states the purpose but fails to disclose behavioral traits like what the bundle consists of, required permissions, side effects (e.g., packages are grouped), or how the output is used later. This is insufficient for a tool that creates a composite entity.

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

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

The description is a single sentence, but it sacrifices informativeness for brevity. It omits crucial details about parameters and behavior, making it under-specified rather than concise.

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

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

Given the complexity (1 parameter with unknown structure, no output schema, no annotations), the description is severely incomplete. An agent cannot confidently use this tool without more information about the request body format and expected outcome.

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

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

The input schema has one parameter 'body' with no defined properties (additionalProperties: true) and 0% schema description coverage. The description does not elaborate on what the body should contain (e.g., list of package IDs, shipping details), leaving the agent completely in the dark about how to construct the request.

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

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

The description states 'Create a bundle of packages for international shipping', which clearly identifies the verb (create), resource (bundle of packages), and context (international shipping). It distinguishes this tool from related siblings like ebay_create_package (creates a single package) and ebay_get_bundle (retrieves a bundle).

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

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

The description provides no guidance on when to use this tool versus alternatives like ebay_create_package or when not to use it. There is no mention of prerequisites, such as needing to create packages first, or scenarios where this tool is appropriate.

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

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

Annotations only declare readOnlyHint=false, so the description carries the rest of the load and does so well: it discloses the sell.account authorization requirement, that marketplaceId is transmitted as the X-EBAY-C-MARKETPLACE-ID header, and that a successful call yields 204 No Content with no body. It omits any error/failure behavior or rate-limit context.

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

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

One dense but front-loaded paragraph that opens with the action and proceeds to body composition, auth, and verification. Every sentence earns its place, though the parenthetical API reference and enum-heavy phrasing make it slightly harder to scan than it could be.

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

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

For a mutation tool with no output schema and a deeply nested request body, the description covers what to send, which permission is needed, how the marketplace is transmitted, what a success response looks like, and how to verify the result. Nothing essential to correct invocation is missing.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description meaningfully adds to it: it decomposes the shippingRules object into calculatedShippingRule (weight/item/cost-based discounts), calculatedHandlingRule, and combinedDuration, and explains the header mapping for marketplaceId. This goes beyond what the schema alone conveys.

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

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

States a specific verb and resource ('Create calculated combined-shipping rules') and scopes it to listings that use calculated shipping, which distinguishes it from the sibling ebay_create_flat_shipping_rules and ebay_create_promotional_shipping_rule. An agent can pick this tool without opening the schema.

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

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

Gives clear context: it applies to listings using calculated shipping, requires the sell.account scope, and points to ebay_get_combined_shipping_rules as the confirmation step. It does not explicitly contrast with ebay_update_calculated_shipping_rules or state exclusions, so it stops short of a 5.

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

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

Annotations include only readOnlyHint: false, and the description merely restates the create action without adding behavioral context. It does not disclose idempotency, required prior setup (such as having a seller account or opted-in program), the outcome of a successful creation, or potential side effects. The description adds no transparency beyond what the annotation already implies.

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

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

The description is a single sentence, but it is under-specified and mostly restates the tool name. 'Create campaign through the eBay Marketing API' adds only marginal context (the API family) and fails to structure important details such as required fields, campaign types, or links to additional workflows. This is under-specification, not efficient conciseness.

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

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

The tool has a complex nested schema (budget, fundingStrategy, campaignCriterion, etc.) and a large sibling context, yet the description provides no awareness of these fields, required elements, or operational constraints. Without an output schema and with only a single generic sentence, an agent cannot determine what constitutes a valid campaign creation request or how to handle edge cases. The context is incomplete for a complex mutation operation.

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

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

Schema description coverage is 100% at the top-level request parameter, which has a brief description ('Create campaign request body'). However, nested fields like campaignName, marketplaceId, and startDate have no descriptions. The tool description provides no additional parameter semantics, so it does not compensate for the inner fields, but the baseline of 3 applies due to high schema coverage.

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

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

Description states a specific verb ('Create') and resource ('campaign'), so an agent knows the basic operation. However, it does not differentiate from sibling tools like ebay_setup_quick_campaign, ebay_clone_campaign, or ebay_launch_campaign, which also relate to campaign creation. It is clear at the verb+resource level but lacks sibling differentiation.

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

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

There is no guidance on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., opting into the advertising program), campaign types, or conditions under which the agent should choose this over ebay_setup_quick_campaign or ebay_clone_campaign. No when/when-not guidance is provided.

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

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

No annotations provided and description does not disclose behavioral traits like authentication needs, side effects, or whether the tool is read-only or destructive. The mere mention of 'create' implies mutation but lacks context.

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

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

The description is extremely brief (one short sentence), but this brevity sacrifices necessary information. It is not front-loaded with key details beyond the basic purpose.

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

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

Given the complexity (no output schema, one parameter with no structure, no annotations), the description is woefully inadequate, lacking return value, error handling, or parameter guidance.

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

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

Schema description coverage is 0% and the description provides no details about the 'body' parameter structure or required fields. The parameter is a black box.

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

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

The description clearly states the verb (create), resource (complaint), and context (international shipping). It distinguishes from sibling tools as no other complaint creation tool is present.

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

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

No guidance on when to use this tool versus alternatives. No mention of prerequisites or when not to use.

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

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

No annotations are present, so the description must carry the full burden of behavioral disclosure. It only says 'Create' which implies mutation, but provides no details on idempotency, overwrite behavior, side effects, or required permissions. This is a significant gap for a creation tool.

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

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

The description is a single sentence, which is concise but lacks structure. It could benefit from additional sentences or bullet points to cover parameter details and behavioral context while remaining concise. Currently, it under-specifies.

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

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

Given the complexity of a creation tool with a freeform body and no output schema or annotations, the description is severely incomplete. It does not explain return values, error conditions, prerequisites, or how to interact with related tools like ebay_get_consign_preferences. The agent cannot reliably use this tool based solely on this description.

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

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

The input schema has one parameter 'body' which is a freeform object with no defined properties (schema description coverage 0%). The description adds no meaning about what fields the body should contain, how to structure it, or any constraints. This leaves the agent completely uninformed about how to populate the parameter.

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

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

The description clearly states the action ('Create') and the resource ('consign preference for international shipping'). It is specific enough to distinguish from siblings like ebay_get_consign_preferences. However, it does not explain what a consign preference is, which would be helpful for complete clarity.

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

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

No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives, nor does it mention any prerequisites or conditions. The agent is left to infer context from the sibling list.

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

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

With only readOnlyHint=false in annotations, the description carries the full behavioral burden and does so effectively: it discloses asynchronous execution, the 202 response, returned taskId and Location, the sell.analytics.readonly scope, and the CURRENT-evaluation limitation. It does not contradict the annotations.

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

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

The description is front-loaded with the core purpose, then efficiently layers prerequisites, response behavior, and follow-up steps. It is dense and slightly run-on, but nearly every clause earns its place given the nested schema and multi-step workflow.

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

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

For a complex asynchronous task-creation tool with no output schema, the description supplies all needed context: required parameters, evaluation constraint, authentication scope, response details, and the polling/download continuation path. An agent has enough information to invoke and follow through correctly.

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

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

Schema description coverage is 100%, so the schema already documents all parameters in detail. The description largely restates those parameter rules (feedType, schemaVersion, filterCriteria values, acceptLanguage default) without adding meaningful semantics beyond what the schema provides, making the baseline of 3 appropriate.

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

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

The description uses a specific verb (Create) and names the exact resource (an asynchronous Feed API customer service metrics report task), including the required feedType. This clearly distinguishes it from generic sibling tools like ebay_create_feed_task and the read-side ebay_get_customer_service_metric_task.

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

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

It explicitly says to check ebay_get_customer_service_metric first to avoid tasks with no evaluation, and then describes the follow-up workflow: poll ebay_get_customer_service_metric_task and download with ebay_get_feed_task_result_file. This gives clear when-to-use and sequencing guidance.

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

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

The readOnlyHint=false annotation already flags this as a mutating operation, and the description says 'Create' consistently. However, the description adds no extra behavioral context, such as whether a policy ID is returned, whether creation can overwrite an existing policy, or what validation or failure behavior to expect.

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

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

The description is a single, clean sentence with no filler and the action front-loaded. It is concise, though slightly under-specified in content.

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

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

For a tool with a nested required object, no output schema, and no parameter descriptions, this description is too thin. It does not explain what a valid custom policy requires, what constitutes a policy type, or what the agent should expect after calling it.

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

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

The schema has 0% description coverage, and the description does not mention the required 'policy' object or its required 'name' and 'policyType' fields. The agent is left to infer meaning from field names alone, with no guidance on allowed or expected values for 'policyType'.

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

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

The description states a clear verb and resource: 'Create' a 'custom policy'. It does not differentiate custom policies from the many sibling policy-creation tools (e.g., create_fulfillment_policy, create_payment_policy), but the core purpose is unambiguous.

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

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

There is no guidance about when to use this tool, what prerequisites exist, or which sibling tools to prefer. The agent is not told how this relates to ebay_get_custom_policy, ebay_update_custom_policy, or the other create_*_policy tools.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate those. The description adds useful context: it's a staging operation (not a final upload), requires sell.inventory, and returns a documentId for a subsequent call. However, it doesn't disclose what happens to previously staged documents, whether this creates a persistent resource, or any rate limits. With annotations covering the basic safety profile, a 3 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.

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

Two sentences with no filler. The core action, key parameters, return value, downstream tool, and required permission are all packed efficiently. Front-loaded with the verb and resource.

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

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

For a 2-parameter tool with 100% schema coverage and no output schema, the description is nearly complete. It explains the staging purpose, the return value, the downstream step, and the permission requirement. The only minor gap is not describing the response format or any side effects, but the description is sufficient for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters with examples (ENGLISH, USER_GUIDE_OR_MANUAL). The description adds the relationship between the parameters and the staging purpose, but doesn't add meaning beyond what the schema provides. Baseline 3 is correct.

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

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

The description states a specific verb ('Stage') and resource ('a listing document'), and names the two key parameters (documentType, languages). It also mentions the return value (documentId) and the downstream sibling (ebay_upload_document), which helps distinguish it from the many other ebay_* tools. However, it doesn't explicitly contrast with the closely related ebay_create_document_from_url, so it's not a full 5.

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

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

The description implies the usage context: this is the first step in a two-step document upload flow, and the returned documentId is meant for ebay_upload_document. It also states the required permission (sell.inventory). It doesn't explicitly say when NOT to use it or name alternatives like ebay_create_document_from_url, but the staging-then-uploading flow is clear enough.

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

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

Annotations show it is a mutating but non-destructive call; the description adds the sell.inventory OAuth scope, 10 MiB size cap, and the acceptance-check workflow. No contradiction. It does not describe response or failure modes, but the valuable context goes beyond structured annotations.

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

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

Two compact sentences front-load the core action and constraints, then give the required follow-up. No filler.

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

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

Covers the operation, formats/size, required scope, and next step via ebay_get_document, which is enough to invoke it correctly. The only notable omission is the exact return shape/document ID, but the get_document handoff partially compensates for the missing output schema.

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

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

Schema already describes languages and documentType with examples; the description adds important semantics for documentUrl by declaring accepted remote file types and size, which the schema does not cover. It doesn't enumerate valid enum values, but the examples plus URL constraint provide a workable baseline.

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

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

The description names a concrete operation (create), a resource (listing document), and a distinctive input source (HTTPS URL). It also enumerates accepted formats and size, making it easy to distinguish from sibling create/upload tools.

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

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

Provides clear context: use when you have a supported URL and need a document for a listing, and explicitly prescribes checking ebay_get_document for ACCEPTED before attaching. It stops short of naming the preferred alternative (e.g., ebay_create_document) or saying 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.

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

The only annotation is readOnlyHint: false, which is consistent with a create operation. The description adds no behavioral detail beyond the act of creating – no mention of side effects, required permissions, or rate limits. It adds minimal value over 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.

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

The description is one sentence, eight words, and front-loaded with the action. No wasted words, though it sacrifices useful context for brevity.

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

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

For a tool with a nested request object and no output schema, the description is insufficient. An agent cannot know what fields like itemIds, audiences, scheduleDateType mean, or what the API returns. The schema shows required fields but the description contributes no guidance.

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

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

Schema description coverage is 100% for the two top-level parameters. The description does not explain how to populate the nested request object or clarify that marketplaceId appears both at top level and inside request. It relies entirely on the schema, which only gives a generic 'Create email campaign request body'.

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

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

States a specific verb ('Create') and resource ('email campaign'), and clarifies it uses the eBay Marketing API. This distinguishes it from sibling tools like ebay_create_campaign (regular ad campaigns) and from ebay_update_email_campaign/ebay_get_email_campaign.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention that for standard promotions or other campaign types other tools should be used, nor does it note prerequisites like having an audience already defined.

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

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

With only readOnlyHint=false in annotations, the description carries strong extra context: the 201 success response, that scheduleId and Location are returned, the per-feed-type schedule quota (error 160031), the required sell.fulfillment scope, and the LMS_ORDER_REPORT constraint. This is exactly the load-bearing detail 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.

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

Front-loaded with the core purpose and generally dense with facts, each clause earning its place (template dependency, response, quota, scope, feed-type limit). It is a single long run-on sentence, which slightly impairs scanning, but no throwaway content.

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

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

For a mutation tool with no output schema, it covers prerequisites, request composition, response codes, returned identifiers, quota limits with the error code, and required auth scope. Nothing material an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by enumerating the key fields and, more importantly, tying them to the template (schemaVersion and trigger fields are conditional 'as the template requires'), which helps the agent understand their interdependency beyond the per-field schema text.

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

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

States a specific verb (Create) and resource (recurring Feed API report schedule), and the 'subscribes to an ACTIVE schedule template' framing cleanly separates it from the get/update/delete_feed_schedule siblings. An agent can identify the operation without opening the schema.

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

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

Clearly specifies the prerequisite: the schedule must subscribe to an ACTIVE template, and it routes the agent to ebay_get_feed_schedule_template to read it. It also restricts the applicable feed type (LMS_ORDER_REPORT). It does not explicitly contrast with a one-time alternative like create_feed_task, so it stops just short of full when/when-not guidance.

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

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

With only readOnlyHint=false as an annotation, the description carries the behavioral burden well. It discloses that eBay answers 202, that the response includes taskId and Location, the OAuth scope dependency, optional header behavior, and reserved feed types.

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

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

The description is dense and front-loaded: purpose and examples come first, followed by response behavior, workflow, optional headers, and OAuth scopes. Every sentence adds relevant information, though the single long paragraph could be slightly more scannable.

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

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

For a complex mutation tool with nested parameters and no output schema, the description is complete. It explains the create-task workflow, dependent tools, return identifiers, header behavior, and authorization requirements, leaving no major gap for an agent invoking the tool.

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

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

Schema description coverage is already 100%, so the baseline is 3. The description adds useful feedType-specific semantics such as OAuth scope mapping and reserved feed types, and reiterates header mappings for marketplaceId and acceptLanguage, going beyond the structured schema.

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

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

The description states a specific verb (create), resource (Feed API upload/download task), and scope (without filter criteria, requiring feedType and schemaVersion). It gives concrete examples such as LMS_ADD_FIXED_PRICE_ITEM, LMS_ORDER_ACK, and Seller Hub feeds, making it easy to distinguish from sibling task tools like ebay_create_report_task or ebay_create_inventory_task.

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

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

It explicitly describes the workflow: create the task, send the file with ebay_upload_feed_task_file for upload feed types, then poll ebay_get_feed_task. It also names the required OAuth scope per feed type and clarifies that certain feed types are reserved by eBay.

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

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

Annotations only supply readOnlyHint=false, so the description carries real extra burden and meets it: it discloses the auth scope ('Requires sell.account'), the response shape ('204 No Content' = nothing returned), and the confirmation step. It stops short of stating idempotency or how it interacts with existing rules.

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

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

The action is front-loaded in the first clause and the parenthetical API path and endpoint name are secondary. Dense but earns most of its length; minor redundancy from restating the endpoint name.

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

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

For a two-parameter write tool with no output schema, the description covers purpose, scope requirement, return value and a follow-up read path, which is enough to call it correctly. It omits edge cases (overwrite/conflict behavior, rule validation limits).

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

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

Schema description coverage is 100%, so the schema already documents marketplaceId (enum + header note) and the shippingRules subfields. The description's header mention ('X-EBAY-C-MARKETPLACE-ID') duplicates what the schema's marketplaceId description already states, so it adds little. Baseline 3.

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

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

States a specific verb and resource ('Create flat-rate combined-shipping rules') and pins the API endpoint (Account API v2 createFlatShippingRules), which lets an agent distinguish it from close siblings like ebay_create_calculated_shipping_rules and ebay_create_promotional_shipping_rule without opening a schema.

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

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

It gives a verification path ('confirm with ebay_get_combined_shipping_rules') and a scope requirement ('Requires sell.account'), but never states when to choose this over its near-identically named siblings (create_calculated_shipping_rules, create_promotional_shipping_rule, update_flat_shipping_rules). Usage is only implied by the resource name.

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

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

The description discloses the exact error text, explains the confusing DomesticItemShippingService[0]/[1] citation as remote validation rather than client duplication, warns that the sandbox accepts a smaller code set, and states the required OAuth scope. These details go well beyond the sparse readOnlyHint=false annotation.

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

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

The description is long but dense and front-loaded, with the purpose stated first and the most error-prone constraint explained next. The known-good payload sketch is compact and useful, though the OAuth scope is stated twice in slightly different forms, which is a minor redundancy.

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

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