Obriym CRM

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

Annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false). The description adds non-obvious behavior the annotations cannot: the order total is recomputed as a side effect, the exact 409 CONFLICT message for disallowed statuses, and that the response echoes the operating workspace.

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 action and constraint, then alternatives and the return hint. No filler sentences; every clause carries information the agent needs before calling.

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 6-param mutation with no output schema, the description supplies the mutation side effect, the state precondition with its exact failure mode, the sourcing path for identifiers, and a note on the response payload. Nothing needed 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 baseline is 3, but the description adds sourcing guidance beyond the schema by telling the agent where externalId comes from (list_orders/create_order) and that productName should be quoted from search_products. It adds meaning for the two most error-prone fields.

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+resource ('Add a line item to an existing order') and scopes it by externalId, which cleanly separates it from create_order, update_order_item, and remove_order_item in the sibling set.

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 states in which it is allowed (pending/confirmed) and the states that produce a 409, and routes the agent to list_orders/create_order for the externalId and search_products to source a real product. When-to-use and when-not-to-use are both covered.

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 non-readOnly, non-idempotent, openWorld, non-destructive. The description restates 'Not idempotent: repeating the call adds the photos again' (matching idempotentHint=false), and its true added value is the operational detail: it downloads and stores its own copy, format/2MB/10-photo limits, and all-or-nothing refusal semantics. Useful context beyond annotations, though the safety profile is mostly carried by the structured fields.

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

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

Front-loaded with the core action and scope, then limits, then atomicity and return. Dense but every sentence carries distinct information (limits, atomicity, non-idempotency, version check). It is long for a 3-param tool, which keeps it from a 5.

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?

No output schema exists, and the description explicitly documents the return (full photo list {url, alt}, first is the main photo). It covers limits, atomicity, side effects through the product form operation, and routing context — nothing material is left out.

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 is 3, but the description adds real meaning the schema doesn't: the files field is filled by ChatGPT itself while other clients pass images or use create_image_upload, and the relationship/composition of the two arrays. It goes beyond restating field docs.

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+resource+scope: 'Add photos to ONE product, after the photos it already has.' It explicitly differentiates itself from the sibling update_product_images (reorder/caption/remove) and get_product, so an agent can select it without opening schemas.

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

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

Names the three input routes (public https links via images, ChatGPT-attached files via files, or create_image_upload for local files) and the routing alternative: use get_product first to inspect, update_product_images to modify existing photos. Explicit when-to-use and 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?

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds substantial context: stock history is recorded, reason/delta contradictions are rejected, non-tracked products and bundles return conflicts, externalId makes retries idempotent, and new stock is pushed to connected sales channels. These are meaningful behavioral traits beyond the annotations.

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

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

The description is long but front-loaded and well structured: it starts with the core operation, then covers usage, reason constraints, conflict cases, idempotency, and side effects. Every sentence carries operational value, and the ordering follows what an agent needs to decide whether and how to call the 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?

Given a six-parameter mutation tool with no output schema and annotations that only cover safety hints, the description is nearly complete: it covers behavior, validation, conflicts, idempotency, and side effects. The main gaps are the unexplained optional parameters (note, metadata) and only a minimal statement about the return value.

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%, so the description must carry the burden. It adds important semantics for delta (relative, negative/positive), reason (direction rules and vocabulary), and externalId (idempotency), but it does not explain note or metadata at all, leaving two of six parameters undocumented.

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 ('Move a product stock by a relative delta') and immediately distinguishes the operation from an absolute stock set. It also names the precise scenarios it serves (correction, write-off, damage) and contrasts its behavior with an order commit that might otherwise overwrite stock.

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 this is the correct tool for correction, write-off, or damage, and that it never sets an absolute number. It also gives clear when-not guidance for bundles ('adjust each component instead') and explains how reason constrains the allowed delta direction.

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

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

Annotations already cover destructive/non-idempotent/openWorld, yet the description adds material behavior: which numbers reach connected channels versus the never-published purchase cost, the CONFLICT-on-drift mechanism, the required owner switch in Settings, and the return shape { affected, skipped }. This is well beyond what the structured fields disclose.

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 the step-2 relationship, then dense but non-redundant detail. It is long, but nearly every clause (conflict handling, switch requirement, non-idempotency, confirmation) earns its place; minor tightening would help.

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 destructive, non-idempotent bulk mutation with no output schema, the description supplies the return shape, the safety gate, the failure mode, and the confirmation expectation. An agent has everything needed to call it correctly and to explain the outcome to a person.

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 rule/scope/target/digest are already richly documented in the schema, and the digest field itself already says 'copied verbatim, never invented.' The description reinforces the 'send the SAME ...' contract but adds little parameter meaning the schema lacks, so 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?

Opens with a specific verb+resource and immediately positions the tool as 'step 2 of 2, after preview_bulk_price_change', so the agent can distinguish it from the sibling preview tool without opening either schema. It also states the concrete effect (changes real prices).

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 explicit when-to-use (only after a preview, sending the SAME rule/scope/target/digest), when-not (never repeat a successful apply), refusal conditions (CONFLICT on digest mismatch, missing owner switch), and the confirmation policy ('confirm with the person unless they asked for the change outright'). Rarely does a definition cover this much routing and gating.

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 say destructive/idempotent/openWorld=false; the description goes well beyond by disclosing that nothing is erased and how to reverse it, the heldByBundle partial-failure mode, the notAttempted takedown semantics via Prom, the meaning of skipped (already archived), and the exact return fields. That is exactly the mutation/partial-success context an agent needs before calling a destructive 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 the action and its role, and nearly every clause carries required behavioral detail (restoration, bundle blocking, takedowns, return fields). It is dense to the point of being slightly clause-heavy, and the trailing 'The result echoes the workspace' is cryptic, but there is little outright waste.

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 takes on the burden of explaining the return shape ({ affected, skipped, notAttempted, heldByBundle }) and the meaning of each field, plus partial-failure and reversibility semantics. For a destructive batch tool, nothing material 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% and there is only one parameter, whose schema already documents the 100-id maximum and that ids come from search_products. The description restates 'up to 100 products' but adds no new syntax or format detail beyond the schema. 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 ('Archive up to 100 products') and immediately scopes it as the removal path ('this is how an AI client removes a product'). It distinguishes itself from update_product (restore path), withdraw_ebay_listings (live eBay listings), and rules out hard deletion over MCP, so an agent can route correctly without reading siblings' schemas.

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

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

Explicit when-to-use (removing a product), explicit when-not/alternative paths (update_product with status active or draft to restore; withdraw_ebay_listings to end a live eBay listing), and an explicit blocker condition (products held by a non-archived bundle are not archived — handle bundles first). Nothing is 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds further context by explaining the unassign behavior ('pass assignedTo=null to unassign') and the return echo ('The result echoes the operating workspace'), which goes beyond the structured annotations without contradicting them.

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

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

The description is three concise sentences: first states the core action, second provides usage guidance, third notes the return behavior. It is front-loaded and every sentence provides useful information without repetition.

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, the annotations, and the absence of an output schema, the description covers the purpose, parameters, prerequisites, and a return detail. It could mention overwriting existing assignments or side effects of unassigning, but it is largely complete for a straightforward mutation tool.

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

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

Schema coverage is 100% and both parameters already have clear descriptions ('The lead id returned by search_leads' and 'User id of the workspace member... Pass null to unassign'). The tool description mostly reinforces these without adding new semantic detail, so the baseline of 3 is appropriate.

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

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

The description opens with a specific action: 'Assign a lead to a workspace member by user id,' and also covers the null case for unassignment. This clearly distinguishes it from sibling tools like update_lead or convert_lead by focusing on the assignment/reassignment act.

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 workflow guidance: 'Use search_leads to find the lead id and get_workspace_info to confirm the operating workspace.' It explains the prerequisite steps but does not explicitly mention when not to use this tool or name alternatives, so it misses the highest bar.

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

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

Annotations already cover the destructive/idempotent/open-world profile, but the description adds real context beyond them: the policy is validated against eBay once before any write, cross-marketplace listings fail with marketplaceMismatch rather than being moved, and writes are refused until the workspace owner enables AI publishing. It also documents partial-failure and time-budget semantics (notAttempted). No contradiction with annotations.

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

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

A single dense paragraph that front-loads the core action and scope before the edge cases. Almost every clause earns its place (validation order, failure mode, auth gate, retry rule), though the density makes it slightly heavy for a 3-parameter 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?

With no output schema, the description supplies the return contract (per-product status of updated/unchanged/saved/unverified/failed plus counts and notAttempted) and the required auth prerequisite. Combined with the 100% schema coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so fulfillmentPolicyId, marketplaceId and productIds are already documented in the schema, including the null-means-default semantics and the 25-id cap. The description restates the maximum and the null behavior rather than adding new meaning, so 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 with scope: set one eBay fulfillment policy on up to 25 products on one site. It explicitly names the sibling it mirrors (set_product_ebay_fulfillment_policy) and differentiates itself as the bulk variant, so an agent can route between them without opening either 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 operating conditions: one policy for many products, null reverts to the connection default, and notAttempted ids should be re-submitted. It does not explicitly state when to prefer this over the single-product sibling, leaving that inference to the agent, so it falls short of a full 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 already cover the read-only, non-destructive, closed-world profile, and the description adds substantial behavioral context beyond them: the blocked-vs-warnings semantics, the meaning of each warning class, the NOT_FOUND failure mode when a channel is not connected, and a firm guarantee that 'this never publishes anything.'

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?

Dense but front-loaded — the core purpose leads, followed by output semantics, platform coverage, and error behavior. Every sentence carries information (fixes grouping, blocked/warnings, error mode), though the parenthetical warning examples run long and could be tightened.

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 carries the full burden and delivers: it explains the returned structure (blocked vs warnings, grouped by fix), the failure mode, and platform coverage. Nothing an agent needs to invoke or interpret the result 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 platform slug is documented in the schema. The description adds value beyond it by clarifying that only some platforms (prom, rozetka, google_merchant, olx) support local checks and that the slug comes from list_marketplaces, giving per-platform behavioral meaning the schema alone does not convey.

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?

Specific verb and scope: 'Check locally which products a marketplace will refuse and why' names the exact resource (products per marketplace) and the failure categories (missing price, blank name, unmapped category). It clearly distinguishes itself from siblings like get_marketplace and list_marketplaces, so an agent can pick it 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?

Explicit when-to-use and when-not: 'without calling the marketplace' establishes the local-check use case, and it names the platforms with local checks (prom, rozetka, google_merchant, olx) versus others that 'report their connection state through get_marketplace instead.' It also routes the agent to list_marketplaces for connection status.

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

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

The description discloses that the result echoes the operating workspace, adding behavioral context beyond the destructiveHint annotation. It doesn't describe other side effects, but the annotation already signals a state-changing 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?

Two sentences, each with a distinct purpose: the first states the action and allowed activity types, the second gives the workflow and result. 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 single-parameter mutation tool with no output schema, the description fully covers what the tool does, how to use it, and what to expect in the response. It is 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?

The schema already documents the id parameter with the same source (list_activities), so the description adds no new semantic information beyond reinforcing the prerequisite identified in the schema.

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

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

The description uses the specific verb 'mark as completed' and specifies the resource 'activity (task, call, or meeting) by its id', clearly distinguishing it from sibling tools like create_activity and list_activities.

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 instructs users to call list_activities first to obtain the id, providing clear usage workflow. However, it doesn't explicitly contrast alternatives or state when not to use this tool.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, so the safety profile is covered, yet the description still adds real behavioral detail beyond them: partial-update merge semantics, that wipLimit null removes the limit, that a blank or duplicate name yields 409 CONFLICT, that stage order/terminal behavior are immutable, and that the response echoes the operating workspace.

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?

Four tight sentences, front-loaded with the action and the field list before the patch contract and edge cases. Every clause carries load: field scope, id provenance, merge behavior, null semantics, conflict condition, and immutability.

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 nested patch object, the description covers everything needed to call it correctly: required inputs, partial-update behavior, the null-removal case, the conflict failure mode, immutability boundaries, and what the response echoes.

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 id, name, wipLimit and defaultProbability, making 3 the baseline. The description earns above that by supplying the cross-field patch rule and the name-uniqueness/409 constraint, which the schema does not express (its minLength only rules out blank names, not duplicates).

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 (Update) plus the exact resource (an existing pipeline stage) and enumerates the three mutable fields (name, default probability, WIP limit). It also fences off what the tool is not ("Stages cannot be created here"), which cleanly separates it from creation tools and from list_pipeline_stages, which it names as the id source.

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 tells the agent where to get the id (from list_pipeline_stages), the patch contract ("ONLY the fields to change — omitted fields keep their current value"), and the when-not conditions (stages cannot be created here; order and terminal behavior are fixed). No inference is required to pick this tool over a sibling.

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 flag this as destructive and not read-only. The description adds value by specifying the behavioral side effect: 'Sets the lead status to converted,' and by noting that 'The result echoes the operating workspace.' There is no contradiction with 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 only three sentences, and every sentence earns its place: the first defines the operation and constraint, the second states the status side effect, and the third gives the prerequisite and result behavior. There is no redundant or filler content.

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

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, the description covers the key prerequisites, the at-least-one constraint, and the side effect on lead status. The nested input object is fully documented by the schema. The only minor gap is not describing the exact result shape beyond echoing the workspace, but the schema and annotations carry enough 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?

The input schema covers 100% of parameters, which provides a strong baseline. The description adds important cross-parameter guidance not encoded in the schema: 'select at least one via the input flags.' It also reinforces that the id comes from search_leads, which helps the agent wire the required id parameter correctly.

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, specific action: converting a lead into a contact, company, and/or deal, and sets the lead status to converted. This clearly distinguishes it from sibling tools like create_contact, create_company, create_deal, and update_lead because it describes a compound conversion operation with a status side effect.

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 a concrete prerequisite: 'Use search_leads first to find the lead id.' It also communicates the core usage context (converting an existing lead into one or more record types). It does not explicitly name alternatives or say when not to use this tool, but the context is clear enough for an agent to choose it correctly.

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 flag this as non-read-only and non-destructive; the description adds a non-obvious business constraint (must link at least one entity) and notes that the result echoes the operating workspace. This goes beyond the structured flags and contains no contradiction.

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, front-loaded with the primary action, and every clause adds information: activity types, the linking requirement, and the source for entity IDs. No filler or repetition of the title.

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 12 parameters and no output schema, the description covers the central workflow and linking requirement but leaves the return value ambiguous ('echoes the operating workspace') and doesn't describe the creation result. It's adequate for invoking the tool but not fully 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?

Schema description coverage is 100%, so every parameter is already documented. The description reinforces the 'link at least one entity' rule and points to search tools, but these details are largely already present in the schema's per-parameter descriptions, providing only marginal extra meaning.

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, enumerates the five allowed activity types, and names the entity types that must be linked. This clearly distinguishes create_activity from sibling read/update/complete activity tools and from other create_* 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?

It states the core use case and gives a concrete prerequisite: at least one linked entity, with search_leads/search_contacts/search_companies/search_deals explicitly named for obtaining IDs. It doesn't explicitly contrast with complete_activity/get_activity/list_activities, but the context 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 already declare it is not read-only and not destructive, but non-idempotent. The description adds genuinely useful behavior: duplicate names are rejected, the slug is normalized to Latin, and translations REPLACE the whole set rather than merging. It also explains the return payload and how the id feeds create_product/update_product.

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 action, then the critical name-verbatim constraint, duplicate check, and translation discipline. Every sentence carries weight, though the translation-fidelity sentence slightly overlaps the schema's own wording.

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?

No output schema exists, yet the description explains the result (created brand with id, operating workspace echoed). Combined with full schema coverage and the duplicate/translation constraints, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantics beyond the schema: the name must be sent verbatim as the marketplace knows the vendor, translations must not invent facts, and the returned id is the brandId for product tools. This is meaningful guidance even if some overlaps with per-field descriptions.

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

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

States a specific verb and resource (create a catalog brand) plus the scope of optional fields (description, website, per-language translations). It contrasts cleanly with siblings list_brands and update_brand, so the agent can distinguish creation from listing/editing 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?

Names an explicit prerequisite: call list_brands first because a duplicate name is rejected. That is a real usage instruction, but it does not say when to prefer update_brand over create, nor when creation is inappropriate.

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?

Adds real behavior beyond the annotations: slug is force-normalized to Latin regardless of input, the parent must already exist in the workspace, a duplicate name under the same parent is rejected, and the response echoes the operating workspace. The translation instruction ('add no facts the user did not give') is a behavioral constraint the agent would otherwise have to guess, and none of this contradicts the readOnly=false / destructive=false / idempotent=false hints.

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?

Four sentences, front-loaded with the core action, then constraints, then the return value. Every sentence carries distinct information (normalization, prerequisites, translation rule, output contract) with no repetition of the schema.

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?

There is no output schema, so the description correctly fills that gap by describing the created object, its id and the workspace echo. Combined with the prerequisites and uniqueness rule, an agent has everything needed to call a 6-parameter mutation 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%, so the baseline is 3 and the schema already documents each field. The description still adds meaning by tying the returned id to categoryId on create_product/update_product and by constraining what translations may contain, which the schema does not express.

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+resource ('Create a catalog category') and immediately scopes it with nesting, description and per-language translations, which cleanly separates it from update_category, list_categories and create_product in the sibling list. 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?

Gives an explicit precondition ('call list_categories first to avoid duplicates') and downstream routing ('use it as categoryId for create_product/update_product'). It stops short of naming when NOT to use it (e.g. use update_category for an existing category), so it is clear context rather than full when/when-not coverage.

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

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

Annotations cover basic safety traits (readOnlyHint false, destructiveHint false), and the description adds valuable behavioral context: uniqueness enforcement within the workspace, workspace plan limit enforcement, and that the result echoes the operating workspace. This goes beyond what annotations provide, though it could be slightly clearer about failure behavior or response format.

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 three sentences long, front-loaded with the core action, and every sentence earns its place: the resource, the uniqueness constraint, the plan limit, the result echo, and the search-first guidance. No fluff or redundancy.

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

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

For a simple create operation with 6 parameters and no output schema, this description is complete enough for an agent to invoke it correctly. It covers prerequisites (search first), constraints (unique name, plan limit), and operational context (workspace echo). The absent return value documentation is not a significant gap for this tool type.

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 beyond the schema by explaining that the name must be unique in the workspace and that the workspace plan limit is enforced, both of which affect the 'name' parameter and the operation as a whole. This added context justifies a score above 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 clearly states 'Create a company (B2B account)' with a specific verb and resource. It distinguishes from sibling create_* tools (create_contact, create_deal, etc.) by targeting companies specifically, and adds unique constraints (name uniqueness) that further define its scope.

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

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

Explicit guidance is provided: 'Use search_companies first to avoid creating a duplicate.' This tells the agent when to use this tool (after checking for existing companies) and implicitly when not to (when a matching company already exists). It also implies a prerequisite step.

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

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

Annotations cover the safety profile (readOnly=false, destructive=false, idempotent=false), and the description adds real context beyond them: the workspace plan limit is enforced, company/owner links are validated, and the result echoes the operating workspace. Non-idempotency is left implicit, but the added behavioral constraints are substantive.

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 tight sentences with the core action front-loaded, followed by the linking guidance and behavioral constraints. No filler or redundancy.

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

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

For an 8-parameter create tool with no output schema, the description usefully covers validation, plan limits, and the workspace echo in the result. It is nearly complete, though it could note the non-idempotent duplicate-creation risk that the annotations imply.

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 8 parameters. The description adds only the search_companies sourcing for companyId, which the schema itself already notes, so it provides little incremental value over the structured fields.

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+resource ("Create a contact") and disambiguates the domain object with "(person)", which separates it from create_company and other create_* siblings. An agent can immediately tell what entity is being created.

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 concrete routing guidance: "Use search_companies for the companyId to link an employer", which tells the agent how to source a dependent parameter. It does not, however, distinguish create from update_contact or state when-not-to-use conditions, so it falls short of full alternative coverage.

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 not-read-only, non-idempotent and non-destructive, and the description confirms the draft/no-publish semantics plus the product sell-out side effect on live Telegram/Threads posts. It also discloses the return payload (post id + warnings) and workspace echo. No contradiction, though it does not cover rate limits or attachment failure 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?

Front-loads the most important fact (draft, nothing published) and every sentence carries information. It is a single dense run-on paragraph, however, with no structural separation between inputs, constraints, and returns.

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

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

For a 9-parameter mutation tool with no output schema, the description supplies the missing return contract (post id and warnings to relay, e.g. unready channel or Instagram without image) and the follow-up action, leaving nothing an agent needs to call it correctly unstated.

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 every parameter including the files/hashtags/channel-text interplay and image sources. The description restates these relationships (images via links, ChatGPT-attached files, create_image_upload links, catalog product) but adds little syntax or formato beyond what structured fields provide, so 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 ('Create a social post') plus a critical scope qualifier: 'as a DRAFT — nothing is published.' This immediately distinguishes it from publish_content_post, schedule_content_post, and update_content_post 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?

Gives clear routing: 'Then use schedule_content_post or publish_content_post' for the next step, points to list_content_channels for per-channel limits, and to create_image_upload for local files. It also names the not-idempotent condition that governs repeated calls.

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 write operation (readOnlyHint=false, idempotentHint=false), and the description adds meaningful behavior beyond that: it enforces the workspace plan limit and its result echoes the operating workspace. These are concrete operational details an agent would not otherwise know.

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?

Three sentences with no filler: the action, the required inputs, the source tools for IDs, and the workspace-specific behavioral notes. Every sentence earns its place and the most important information is front-loaded.

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

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

For a 12-parameter create operation with no output schema, the description covers the critical decisions: required fields, where to get stage/company/contact IDs, plan-limit enforcement, and what the response echoes. The remaining parameter details are already well-documented in the 100%-covered schema, so nothing essential 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 baseline is 3, but the description adds value by telling the agent where to obtain valid values for stageId and company/contact IDs. This cross-tool guidance is beyond what the schema provides and materially helps construct a correct call.

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 opens with a specific verb and resource ('Create a pipeline deal'), immediately distinguishing it from sibling tools like create_lead, create_company, or transition_deal. It also names the core required inputs, tightening the scope further.

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 — creating a deal — and explicitly points to list_pipeline_stages for the stageId and search_companies/search_contacts for linking. It does not explicitly state exclusions like 'use update_deal to modify an existing deal,' but the prerequisite guidance is strong enough to route an agent correctly.

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 destructive=true, idempotent=false and openWorld=true, and the description builds on that rather than repeating it: it clarifies the write is real but not buyer-visible, that per-product failures must be looked up in remediation.ebayPlaybook, that it is non-idempotent ('a product that already has a draft fails with alreadyListed'), and that it can time out mid-run. This is unusually rich behavioral disclosure 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 tightly packed — every clause carries operational information (preconditions, failure modes, idempotency, refusals) and none is filler. It is dense enough that a reader must parse several semicolon-joined clauses, which costs a little scannability versus a clean multi-sentence split.

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 carries the return contract itself: created / failed (with a playbook lookup key) / notAttempted and the retry instruction, plus the workspace echo. Combined with the refusal and idempotency notes, an agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so the marketplaceId semantics (omit for single-marketplace connections, use only armed ebayDraftSetup.marketplaceIds, never the connection id) largely duplicate the schema text. The description does add non-schema meaning for productIds provenance and gating (must come from search_products and pass inspect_ebay_listings checks), which lifts it above the 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 with scope: 'Create eBay DRAFT offers for up to 25 products.' It immediately distinguishes itself from publish_ebay_drafts (nothing buyer-visible until then) and implicitly from delete/recreate_ebay_drafts, so an agent can separate it from siblings 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?

Gives an explicit prerequisite ('Run inspect_ebay_listings first and pass only products whose nextAction is create_draft and ready is true'), names the downstream alternative (publish_ebay_drafts), and states when it will be refused (AI publishing off, draft creation unarmed). It also tells the agent what to do on partial failure (call again with the notAttempted ids).

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

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

Annotations declare non-read-only, non-destructive, non-idempotent, but the description adds real context beyond them: link expiry in 15 minutes, a 2 MB per-file ceiling with no resize fallback, refusal behavior for oversized files, the HTTP PUT mechanism, and required scopes (products:write or content:write). It stops short of describing what happens to links if unused, keeping it just under a 5.

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

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

Front-loaded with the purpose and audience, then the mechanics, then the return shape and scopes. Dense but nearly every clause carries operational information; the only slight bloat is the enumerated downstream tool list, which could be trimmed.

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 supplies the return envelope ({ uploads: [{ uploadUrl, expiresAt }], maxBytes, allowedTypes }), the required permissions, and the upload constraints — everything an agent needs to call and then use this tool without guessing.

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% and the single `count` parameter is fully documented with its 1-10 bounds in the schema itself. The description reinforces 'one file per link' but adds no syntax or format detail beyond what the schema supplies, 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: creating one-time upload links for image files. It explicitly distinguishes itself from sibling storage tools (add_product_images, set_brand_image, create_content_post), which take the resulting URL rather than the file itself, so an agent can route correctly.

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 scopes the audience (clients that can read local files and send HTTP requests) and excludes others (chat clients pass links, ChatGPT passes files via the files field). It also names the downstream tools that consume the returned url, giving the full when-to-use chain.

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 idempotentHint=true and destructiveHint=false, but the description adds real substance beyond them: it names the idempotency key (externalId) and the exact re-send behavior, states the email-or-phone requirement, and discloses the workspace plan-limit enforcement and the workspace echo in the result. It does not describe failure behavior when the plan limit is hit, keeping it out of the top band.

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?

Four tight sentences, front-loaded with the core action and the idempotency behavior before the constraints and the sibling pointer. No filler — each clause conveys a distinct operational fact.

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, the description covers the essentials: idempotency semantics, minimum required contact info, plan-limit enforcement, and what the result indicates (landed workspace). It stops short of describing error responses when the plan limit is exceeded, which is the main remaining gap.

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

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

Schema description coverage is 100%, so all seven parameters are already documented, including the email-or-phone constraint and externalId idempotency. The description mainly restates those constraints rather than adding new syntax or format meaning, which is the baseline 3 when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Create a lead') and distinguishes the create path from the update path by naming update_lead as the follow-up for changes. It does not explicitly differentiate from other creation siblings (create_contact, create_deal), but 'lead' is an unambiguous resource and the idempotency/requirement clauses sharpen the scope.

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 clear routing hint ('Use update_lead to change it afterward') and implicitly defines when this tool applies. However, it offers no guidance on when not to use it — e.g. checking for an existing lead via search_leads, or relationship to convert_lead — so usage context is only partially covered.

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 idempotentHint=true and destructiveHint=false. The description goes beyond annotations by detailing the idempotency key behavior, workspace plan limit enforcement, workspace echo, and snapshot semantics for product fields. It adds meaningful operational context without contradicting any annotation.

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

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

Three sentences, no filler, and the core purpose is front-loaded. Each clause carries distinct value: creation intent, idempotency, workspace plan behavior, and the product-search prerequisite.

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 a complex nested schema and no output schema, the description covers the critical behaviors: idempotency, plan limits, snapshots, and the search_products prerequisite. It omits return-value shape and failure behavior, but the provided guidance is sufficient for correct invocation in most cases.

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 documents externalId idempotency and productName/sku/unitPrice snapshots in detail. The description reinforces those points but adds little new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states the action and resource: 'Create an order with line items.' It also adds distinguishing semantics around idempotency and item snapshots. However, it does not explicitly name sibling alternatives like add_order_item or update_order_status, so it stops short of full 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?

The description gives strong contextual guidance: use a stable externalId, send a unique id like 'mcp-<uuid>', and use search_products first to quote real products. It does not explicitly state when not to use this tool or point to sibling tools as alternatives, which keeps it just below 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 declare only mutability/safety flags; the description then adds substantial non-obvious behavior: draft default, bundle stock being refused with trackInventory/costPrice ignored, productGroupId content inheritance, marketplace-channel joining from the warehouse, and workspace plan-limit enforcement. This is exactly the kind of context annotations cannot carry.

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 dense paragraph that front-loads the core action and default status before the conditional edge cases (bundle, productGroupId, plan limit). Every clause carries real information, though the run-on length makes some rules harder to scan than a segmented format would.

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?

No output schema exists, and the description compensates by noting the result echoes the operating workspace. It covers the high-risk behavioral cases raised by the schema (bundle refusals, inheritance, plan limit), leaving only minor uncovered fields for a 38-parameter 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 only 24% schema description coverage across 38 parameters, the description must compensate, and it does so for the hazardous/ambiguous ones: sku generation and uniqueness, status default, trackInventory/stock interaction, costPrice and stock being ignored for bundles, and productGroupId semantics. Many low-risk params (name, size, tags, dimensions) remain unexplained, keeping this below 5.

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?

Opens with a specific verb+resource ('Create a catalog product') and immediately distinguishes scope by contrasting creation-time defaults with the update path ('publish it by sending status active once it is complete'). An agent can tell this apart from update_product without opening either 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?

Explicitly routes the agent to siblings for prerequisites ('Use list_categories, list_brands and list_warehouses for the ids') and explains the draft-then-publish workflow. It does not name when-not-to-use or contrast against update_product directly, so it stops short of a full 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 already cover destructive/non-idempotent/non-readonly, but the description adds substantial context: schedule deletion, that its own stored images go with it while linked product photos are preserved, the refusal behavior for published posts, and irreversibility. It also discloses the return ('echoes the workspace'), which no annotation supplies.

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 most decision-relevant constraint (deletable states) is front-loaded, and the cascade/refusal/irreversibility clauses each carry distinct information. It is dense and runs several sentences, but nearly every clause earns its place; slight trimming is possible.

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 scope, cascade side-effects, refusal conditions, irreversibility, and even the return value, which compensates for the absent output schema. Nothing material for a 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 100% and the single 'id' parameter is fully documented as the publication id from create/list. The description adds no syntax or format detail beyond that, so the baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb (delete) and resource (content post) plus the exact scope of deletable states: draft, scheduled, or fully-failed. An agent can distinguish it from siblings like archive_products or withdraw_ebay_listings without opening any 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?

Explicitly states when-not: a post published on any channel is refused and its record stays. This gives the agent a clear precondition for calling the tool and clarifies the boundary against publish/schedule siblings.

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?

Goes well beyond the annotations (destructive/idempotent/openWorld) by disclosing that the CRM product is untouched, that it functions even when draft creation is disarmed but still needs the owner's AI publishing switch, and that the outcome buckets are done/failed/notAttempted. This is genuine side-effect and auth context an agent cannot get from annotations 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-loaded with the core action and scope, and each clause carries distinct information (scope, refusal rule, CRM safety, arming caveat, return shape). Slightly dense with caveats, but nothing is wasted.

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 naming the done/failed/notAttempted result buckets and the workspace echo, and it covers the preconditions (draft-only, publishing switch). An agent has enough to call it correctly and interpret the result.

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 single parameter's schema already documents the 25-item cap, the draft-only effect, and the withdraw alternative. The description largely restates those constraints, adding little beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource: deletes the eBay DRAFT offer for products, with a hard scope limit of 25. It clearly distinguishes itself from the live-listing sibling by stating a live listing is refused and pointing to withdraw_ebay_listings.

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 alternative (withdraw_ebay_listings) and the condition that requires it: a live listing must be ended first. It also scopes usage to drafts and notes it works even while draft creation is disarmed, so the agent knows when the tool is and isn't applicable.

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

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

The annotations already flag destructive/non-idempotent/open-world, but the description adds genuinely new behavior: precisely what is destroyed on eBay, what survives on the channel, the refusal conditions, and the post-condition ('articles stay on the channel, ready for a new listing'). This is exactly the extra context annotations cannot carry.

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 definitive action and effect, and nearly every clause carries operational weight. The trailing fragments ('Returns deleted. The result echoes the workspace.') are terse and slightly cryptic, costing a little clarity for the space they save.

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 one-parameter destructive tool with no output schema, the description covers scope, destruction semantics, surviving state, refusal conditions, prerequisites, and return behavior. Nothing an agent needs to invoke it safely 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% and the single parameter is already thoroughly documented (code/productGroupId or id, and how articles become variations). The description adds no syntax, format, or constraint beyond the schema, 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?

Specific verb (delete) plus a precisely bounded resource: an UNPUBLISHED eBay multi-variation draft, with the exact objects removed (variation offers and the inventory item group). It also carves a clear line against the sibling withdraw_ebay_variation_listing, so an agent can distinguish the two operations without opening either 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?

Explicit when-not plus routing: 'A live listing is refused — end it with withdraw_ebay_variation_listing first.' It also names a second precondition (workspace owner must enable AI publishing), giving the agent both the exclusion and the alternative tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's 'Fetch' aligns with those. The description adds useful behavioral context by listing the fields returned (type, due date, completion state, assignee, linked entity), which is especially valuable given no output schema.

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, each earning its place. The first sentence defines the tool's function and output scope; the second provides actionable usage guidance. No filler or redundancy.

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

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

For a simple read-by-id tool with one parameter and good annotations, the description covers the key aspects: what it fetches, the source of the id, and the alternative when the id isn't known. The listed fields mitigate the lack of an output schema.

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

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

Schema has one parameter with 100% description coverage, and the description reinforces the meaning by saying 'by activity id' and that it is 'returned by list_activities.' This adds a concrete source for the id, going beyond the schema's bare description.

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 'Fetch one CRM activity... by activity id' with a specific verb, resource, and scope. It also distinguishes itself from the sibling tool 'list_activities' by emphasizing single-activity retrieval, and the example note reinforces 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?

Provides explicit guidance: 'Use list_activities first when you only know the related lead/deal/contact.' This tells the agent when to use this tool vs. the alternative, and implies this tool is for when the activity id is already known.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's job is lighter. It adds context by specifying return fields ('status, industry, owner and contact links') and the 'when present' nuance, which goes beyond the annotations and helps set expectations.

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

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

Two concise sentences with key information front-loaded. The first sentence states the action and return content; the second provides a use-case alternative. No filler or repetition.

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 simple 1-parameter schema and annotations indicating a safe read operation, the description is largely complete: it explains scope (workspace, by id), return fields, and when to use search_companies first. It does not mention error behavior (e.g., if id not found), but this is minor for a fetch-by-id tool without an output schema.

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

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

Schema description coverage is 100%, with the id parameter already described as 'The company id returned by search_companies.' The description reinforces this but adds no new syntactic or format details beyond the schema, so 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 action: 'Fetch one CRM company in the selected workspace by company id,' which clearly distinguishes it from search_companies and other get_* tools. It also enumerates included attributes (status, industry, owner, contact links), making the purpose unambiguous.

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

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

Explicitly directs when to use an alternative: 'Use search_companies first when you only know the company name.' This implies get_company is for when you have the id, and the phrase 'in the selected workspace' sets context for workspace-dependent usage.

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?

Given readOnlyHint=true and destructiveHint=false in annotations, the description adds useful context by listing included fields and noting they appear 'when present'. It doesn't cover error behavior or response format, but for a simple read-only fetch, the annotations and description together provide adequate 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?

Two sentences, no fluff. The first sentence states purpose and result details, the second gives usage guidance. Every word earns its place.

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 low-complexity tool with a single parameter and no output schema. The description covers what it returns, when to use it, and how to obtain the ID. Some might expect a note on what happens if the contact is not found, but overall it's complete enough for selection and 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?

Parameter id has 100% schema description coverage ('The contact id returned by search_contacts'). The tool description reinforces this by saying 'by contact id' and mentioning search_contacts, but adds no significant new meaning 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 tool fetches one CRM contact by ID, with specific fields (company, owner, tags, communication) and scope (selected workspace). It differentiates from sibling tools like search_contacts and other get_* 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?

It explicitly instructs to use search_contacts first when only a name, email, or phone is known, implying get_contact is for when the contact ID is available. This provides clear when-to-use guidance and directs to the alternative.

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

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

Annotations declare readOnlyHint=true and the description's 'Read-only' statement is consistent with them, so safety is already covered. Beyond that, the description discloses rich return behavior — per-channel text selection (ownText vs main text), length-vs-limit checks, readiness, and either a permalink or the network's error — which is genuinely useful since no output schema exists.

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

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

The purpose and the read-only nature are front-loaded, and the routing guidance is compact. The middle sentence is a dense enumeration of return fields, but every clause maps to something the agent needs to interpret the response.

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 and only one parameter, the description carries the return-value burden and does so thoroughly, covering post-level fields, per-channel fields, readiness, and success/error outcomes. An agent has everything needed to call it and interpret the result.

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% and the single id parameter is fully documented in the schema, including its origin from create_content_post or list_content_posts. The description repeats that provenance without adding syntax or format detail, so 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 opens with a specific verb+resource ('Read one social post') and enumerates exactly what is returned, so an agent can distinguish it from list_content_posts and create/update_content_post 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 explicitly routes the agent: use list_content_posts to find the id, and call this after publish_content_post to report links. Both the precondition and the alternative tool are named, leaving nothing 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about operating in the selected workspace and the specific metrics included, which is useful behavioral information beyond the annotation. No contradiction.

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 the primary action and key details in the first sentence, and a helpful usage tip in the second. Every sentence earns its place with no redundancy or 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?

For a single-read tool with full schema coverage and clear annotations, the description is complete: it states what the summary includes and provides a prerequisite relationship with list_customers. Although there is no output schema, the listed metrics give sufficient expectation of the return value.

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 the parameter description already stating that companyId is returned by list_customers. The tool description does not add further semantics; it simply repeats the 'by company id' detail. Baseline 3 applies because the schema does the heavy lifting and the description adds little extra meaning.

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 'Fetch' as a specific verb, identifies the resource as 'one CRM customer summary', and details the included metrics (health, lifetime value, won-deal). It clearly distinguishes from sibling tools like list_customers or get_company by specifying the exact scope and content.

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 tells the agent to use list_customers first when only the company name is known, implying this tool requires a company ID. This contrast with the sibling list tool provides actionable guidance on when to choose which tool.

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

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

The annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that this is an operational snapshot for the current workspace and lists the specific data elements returned. No contradiction; the added context is useful but not extensive.

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 two concise sentences. The first sentence packs the purpose, scope, and contents; the second provides the alternative tool. There is no filler or redundancy.

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

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

Given the tool's simplicity (zero parameters, no output schema, read-only), the description covers the key behavioral aspects: what it returns, the workspace scope, and how it differs from get_report. It is complete for a dashboard overview 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 input schema has zero parameters, and the description confirms 'Takes no arguments.' Since there are no parameters to document, the baseline of 4 applies. The description's mention of 'this workspace' clarifies the implicit context but does not relate to parameter 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 clearly states the tool returns a dashboard overview snapshot with specific metrics (lead counts, pipeline value, weighted forecast, overdue activities). It distinguishes itself from the sibling get_report by explicitly directing users to use that tool for trend analytics.

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 provides an explicit use case ('what needs attention today' snapshot) and an explicit alternative: 'Use get_report for period trend analytics instead.' This tells the agent both when to use this tool and when to use a different one.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds context about the selected workspace and optional linked data ('when present'), but does not disclose error behavior or other operational traits. This is adequate but not rich.

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 two sentences, front-loaded with the action and result, and the second sentence provides a clear alternative. No redundant words or 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?

For a simple get-by-id tool with one parameter and no output schema, the description adequately covers what is returned (fields and conditional linked data) and usage context. It does not specify not-found behavior, but given annotations and simplicity, this is a minor gap.

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 says 'The deal id returned by search_deals.' The description reinforces this by mentioning 'by deal id' and directing to search_deals, but adds no new semantic detail 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 tool's function: 'Fetch one pipeline deal in the selected workspace by deal id', and lists the returned fields (stage, value, probability, linked company/contact data). It also distinguishes itself from the sibling search_deals by noting when to use that alternative.

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 tells the agent to use search_deals when only the title or related customer is known, implying this tool is for when the deal id is available. This is a clear, explicit usage guideline with an alternative.

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 mark it read-only/non-destructive, and the description reinforces that ('Reads only') while adding behavior the annotations cannot convey: the meaning of PUBLISHED vs UNPUBLISHED, matchesAssignment null semantics, the withoutOffer bucket, and partial results bounded by a time budget with a retry instruction. This is genuine disclosure beyond the safety profile.

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 dense paragraph that is front-loaded with the core action and result shape, with no filler sentences. It is slightly overloaded by stacking status semantics, matchesAssignment, withoutOffer, and notAttempted into one run-on flow, but every clause still carries meaning.

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 carries the return-value burden and does so by describing the per-offer payload and both result buckets. For a one-parameter read tool, an agent has everything needed to call it and interpret partial results.

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 single productIds parameter, so the schema already documents the array source, min/max items, and id origin. The description only restates the 25 cap and the search_products origin, adding no syntax or format detail. 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 (read the eBay offers of up to 25 products live) and enumerates exactly what comes back per offer: fulfillment/payment/return policy ids, shipping policy name, site, status, and matchesAssignment. It also explicitly contrasts with the sibling get_product_ebay_fulfillment_policy, so an agent can distinguish the two without opening schemas.

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

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

Names the alternative tool (get_product_ebay_fulfillment_policy) for a single product's full picture, and gives an explicit recovery path for unresolved products (call again with the notAttempted ids). Both the 'when' and the 'what next' are spelled out.

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 annotations (readOnly, non-destructive, closed-world), it discloses that this reads the CRM only (unlike eBay-side inspection), enumerates the returned fields, and explains the four inclusion states and their remedial actions. That is rich behavioral context the annotations cannot 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 purpose is front-loaded and the content is dense but purposeful; every clause carries meaning. It is a long single paragraph though, so some index/list structure would improve scanability.

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 carries the return-value burden and does so thoroughly, covering listing state, identifiers, per-article detail, connection/arming flags, and the CRM-only scope. Nothing an agent needs to call or interpret it 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% and the single 'model' parameter is fully documented in the schema (code/productGroupId or id, and how articles become variations). The description's mention of the model adds no new syntax or constraints, so 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 states a specific verb (show/read) and resource (a product model as one eBay multi-variation listing) and enumerates what it returns (state, marketplaceId, listingId/Url, groupKey, per-article fields). It is clearly distinguished from sibling read tools like inspect_ebay_variation_listing.

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

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

It names the alternative explicitly ('Use inspect_ebay_variation_listing for eBay's own checks before saving') and explains how to act on each inclusion value (set_channel_membership, delete/end single_listing). It gives clear context but no explicit when-not-to-use 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds value by disclosing the scoping constraint ('in the selected workspace') and detailing the fields included in the response. It does not contradict any annotation, and while it doesn't mention error behavior, the added field context is useful for a get-one-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 two sentences, front-loaded with the key action and resource, and the second sentence provides an important usage alternative. Every word earns its place with no redundancy or 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?

For a simple one-parameter get tool, the description is nearly complete: it specifies the resource, the lookup key, the response fields, and the alternative tool. It slightly lacks explicit statements about response shape or not-found behavior, but the output schema is not provided, and the description's field list partially compensates. Overall it is well-rounded given the tool's simplicity.

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% coverage with a single 'id' parameter described as 'The lead id returned by search_leads.' The tool description reinforces this by saying 'by lead id' and directing users to search_leads when they lack the id. This adds practical context for how to obtain the parameter value, going slightly beyond the schema's description.

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 'Fetch one CRM lead in the selected workspace by lead id', which specifies the verb (fetch), resource (CRM lead), and scope (by lead id in selected workspace). The list of included fields (status, source, assignee, tags, etc.) further clarifies what the tool returns. It also distinguishes from siblings like get_deal or get_contact by explicitly naming the resource type.

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

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

The description provides explicit guidance: 'Use search_leads first when you only know a name, email, phone or company.' This tells the agent exactly when to use an alternative tool, and implies that get_lead is appropriate when the lead id is already known. This is a clear when-to-use vs alternative distinction.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to reassert safety. It adds value by detailing exactly what the read operation returns (adapter states, counts, etc.), which goes beyond the annotations. It doesn't mention performance or pagination, but for a single-resource fetch that's acceptable.

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: the first densely packs the tool's core output, the second gives usage guidance. No wasted words, and the most important information (what it returns) is front-loaded. Excellent conciseness for a tool that fetches a single entity.

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 listing every type of field returned (adapter setup state, last poll, last poll error, catalog-sync outcome, product import, counts). It also covers the prerequisite (list_marketplaces) and related tools, making it fully self-sufficient for an agent to invoke correctly.

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

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

The schema covers the parameter with a description listing valid slugs and pointing to list_marketplaces as the source. The description reinforces this by telling the agent to use list_marketplaces first, adding context on how to obtain the platform value. Since schema coverage is 100%, the baseline is 3, but the explicit workflow hint elevates it to 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 states a specific verb ('Fetch') and resource ('one connected marketplace') and enumerates the exact data returned (setup state, last poll, last poll error, etc.). It clearly distinguishes itself from siblings by naming list_marketplaces, list_channel_products, and check_channel_readiness, so an agent can immediately identify this as the detailed single-marketplace fetch tool.

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

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

The description explicitly instructs to use list_marketplaces first to see connected platforms, and directs to list_channel_products and check_channel_readiness for complementary data. This gives clear when-to-use and when-not-to-use guidance, leaving no ambiguity about the workflow.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds behavioral context by listing what the order detail includes (line items, payments, shipments, returns) and scoping to the 'selected workspace'. This is useful beyond the annotations, though it doesn't describe response formatting or pagination.

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, front-loaded with the primary action and scope, followed by complementary inclusion details and usage note. Every word earns its place with zero 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?

For a simple single-parameter read tool with no output schema, the description fully equips the agent: what it does, what's included, when to use an alternative, and how to obtain the parameter. No missing 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 covers the only parameter (externalId) completely with 'The order externalId returned by list_orders.' The tool description repeats 'by externalId' without adding new meaning, so baseline 3 for high schema coverage 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 'Fetch full order detail in the selected workspace by externalId' with a specific verb (fetch), resource (order detail), and scope (workspace + externalId). It also enumerates included components (line items, payments, shipments, returns), making it distinct from sibling list/get 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?

Explicit guidance is given: 'Use list_orders first when you only know the customer or date.' This directly contrasts with alternatives and informs when to use this tool versus list_orders. The schema description reinforces that externalId comes from list_orders, creating a clear workflow.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds real domain behavior: results can be in any status including draft/archived, and a bundle's stock and cost are derived from components rather than stored directly.

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 dense sentence with the core purpose front-loaded, followed by status/field details and the alternative-tool routing. Slightly heavy on parenthetical detail, but every clause carries 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?

With no output schema, the description compensates by naming the returned fields (price, stock, category, brand) and the status field, plus the bundle-derivation caveat. An agent has enough to call and interpret the result.

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. The description adds a constraint the schema does not express: exactly one of id or SKU must be supplied (both are optional in the schema with no oneOf), which meaningfully guides invocation.

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 (fetch) and resource (one catalog product in the selected workspace) plus the accepted identifiers (id or SKU). It also distinguishes itself from the sibling search_products by noting the differing scope (all statuses vs. active only).

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 tells the agent to provide exactly one known identifier and to use search_products first when unsure, with the reason (search covers active products only). This is clear when-to-use and when-to-use-something-else guidance.

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

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

Annotations already declare readOnlyHint/destructiveHint, but the description goes well beyond them by disclosing the live eBay read (offer.fulfillmentPolicyId is what buyers see now) and the semantics of effectiveSource values (product, connection_default, first_available). This is meaningful behavioral context an agent could not infer from structured fields.

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

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

Front-loaded with what the tool returns and the sibling alternatives at the end. The middle clause enumerating assignedPolicyId/defaultPolicyId/effectivePolicyId is dense, but each item earns its place by clarifying return semantics absent an output schema.

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 carries the return-value burden and does so: it enumerates the policy ids, the effective source enum, and the live offer field. Combined with the 100%-covered single parameter, nothing an agent needs before calling 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% with a single required productId already documented as 'A product id returned by search_products.' The description adds no format, sourcing, or constraint detail for the parameter, 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 precise verb and resource with scope: 'Show ONE product's eBay shipping policy.' It is immediately distinguishable from its siblings list_ebay_fulfillment_policies and get_ebay_offer_policies, which are named directly in the text.

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

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

Explicit routing to alternatives with the condition that selects each: use list_ebay_fulfillment_policies for costs of every policy, and get_ebay_offer_policies to read several products' offers at once. It also marks the operation as 'Reads only,' removing ambiguity about side effects.

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/destructiveHint, yet the description adds substantive behavior: the marginPercent formula (price ÷ cost − 1, explicitly 'not a margin on the price'), the missingRate-true null case when no rate is stated, and the rule that a bundle's cost is derived and cannot be set. These are non-obvious edge cases beyond structured data.

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

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

Front-loads the core purpose and the enumeration earns its place given the tool returns many distinct price structures with no output schema. The long semicolon-chained mega-sentence is dense and slightly harder to parse than a short bulleted breakdown, costing one point.

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 fully compensates by enumerating every returned data group, the derived-cost rule, the marginPercent definition and its rate-missing null behavior. An agent has everything needed to call it and interpret results.

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 a single parameter at 100% schema description coverage, the schema already documents that id is the product id and never a SKU or name. The description's 'Use search_products for the id' reinforces provenance but adds little beyond the schema, 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?

States a specific verb+resource ('Everything about ONE product's prices in one call') and enumerates the exact contents returned: own/old price, currency, price-list rows, channel overrides, wholesale breaks, purchase cost, and markup over cost. This clearly distinguishes it from get_product and list_channel_products.

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 id source ('Use search_products for the id'), the sequencing before set_product_channel_price, set_product_price_tiers or upsert_product_prices, the confirmation-after-change use, and the alternative for groups (preview_bulk_price_change). When-to-use, prerequisites and alternatives are all present.

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 the safe, read-only, closed-world profile, so the description's job is supplementary. It adds genuine behavioral context beyond the annotations: 'Each returns aggregated rows (no per-record data)' and the currency-handling rule ('currencies are reported separately and never added together'). It stops short of describing the row/column shape, but that is a minor residual given the annotation 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?

A single dense paragraph that front-loads the core purpose and the report taxonomy before the period mapping and the alternative-tool pointer. It is appropriately sized for a six-way enum, though the per-report recap partially duplicates the schema's enum description.

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 carries the return-value burden and does so at a useful level of abstraction ('aggregated rows, no per-record data') while mapping each report to its period parameter and pointing to the sibling for a different use case. It leaves the exact output fields unspecified, but the essentials for correct invocation are present.

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% and the report enum's schema description is already exhaustive, so the baseline is 3. The description restates which report uses days/months but adds little syntax or default detail (e.g., the 90/30 and 6-month defaults) beyond what the schema property descriptions already carry.

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 ('Return one aggregated analytics report over a period for this workspace') and enumerates all six report types with their contents. An agent can distinguish this from get_dashboard_overview and from every list/search sibling 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?

Explicitly routes the agent: 'Use get_dashboard_overview for today's operational snapshot instead,' and specifies which report consumes which period parameter (days for lead_source_conversion/team_performance/product_sales, months for revenue_trend, none for pipeline_velocity/stock_valuation). Nothing about selection is 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real operational context beyond that: connection-type distinctions (OAuth vs sign-in), the fact that the server's live tool list may be newer than the caller's, and the prescribed recovery path via server.refreshHint.

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 what the tool returns, then the when-to-call guidance. Dense but every sentence carries weight; the parentheticals and the final sibling reference add length without much trimming opportunity, keeping it just short of ideal.

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?

No output schema exists, so the description must carry the return-value burden itself, and it does so thoroughly by enumerating every response field. It also covers the edge case (stale tool list) and the follow-up tools, leaving nothing an agent needs 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?

The tool takes zero parameters, so there is no parameter semantics to convey; the baseline for a no-arg tool is 4. The description correctly implies a no-argument read of current connection/workspace state.

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+resource (show which account/workspace this connection operates as) and enumerates exactly what is returned: signed-in name/email, workspace name, plan, connection type, granted scopes, plus server version, server.tools and server.refreshHint. It clearly distinguishes itself from list_workspaces and select_workspace, which it names explicitly.

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 explicit triggers ('which account or workspace am I connected to?') and a second non-obvious trigger: when no tool in the list matches the user's request, consult server.tools and relay server.refreshHint rather than refusing. It also names the alternatives (list_workspaces, select_workspace) for viewing or changing the bound workspace.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, and the description reinforces this with 'Reads eBay, never writes'. Crucially it goes beyond the annotations by specifying the per-product payload (eBay state enum, nextAction values, readiness, blocking reason with details) and the supporting fields ebayDraftSetup, remediation.ebayPlaybook and publishingEnabled — none of which appear in any structured field.

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?

It leads with the purpose and the pre-write constraint, then enumerates the return shape, then closes with the call sequence — a logical front-loaded order. It is dense and long relative to a two-parameter tool, though nearly every clause carries information an agent needs.

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?

There is no output schema, and the description compensates by naming the key return fields and their meanings, the effect of owner publish settings, and the remediation mapping. Combined with the 100%-covered input schema and safety annotations, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%: productIds and marketplaceId both carry detailed descriptions, including the enum and the 'omit it when the eBay connection sells on one site' guidance. The description adds only the 'up to 25' cap (already in the schema) and nothing else about parameter semantics, 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 ('Check up to 25 products against eBay') plus the scope ('before any write, with the same live preflight ... the real draft and publish calls run'). This clearly distinguishes it from siblings like check_channel_readiness, create_ebay_drafts and publish_ebay_drafts.

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 explicit sequencing: 'Use search_products first for the ids', and 'after a fix with update_product, upsert_product_prices, upsert_product_attributes or upsert_product_translation, call it again'. It also frames the tool as a pre-write gate, so the when-not (anything after a successful publish path) is implied and the required predecessor tools are named.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true; the description reinforces this with 'writing nothing' and 'Reads eBay,' and adds substantive context by enumerating exactly what is validated (prices, axes, duplicates, category, condition, item specifics, shipping/policies, inventory location) and the prerequisite about arming. It does not discuss latency or cost of the open-world calls, which keeps it from a 5.

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

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

Front-loaded with the core action and the 'writing nothing' guarantee, then the check list, then return shape and prerequisites. The middle checklist sentence is very dense, but every clause carries distinct signal and nothing is padded.

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 naming the returned fields (ready, marketplaceId, categoryId, axes, variationCount, issues with reason/message/skus) and the precondition quirks (marketplace for first save, no arming). An agent has everything needed to call and interpret 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?

Schema description coverage is 100%, so both params are already documented in the schema (model as code/productGroupId, marketplaceId for a first save on multi-marketplace connections). The description adds only the note that a marketplace is needed but arming is not; it adds no format or value semantics beyond the schema, so 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 precise verb and scope: runs the full pre-save validation of a model's eBay multi-variation listing without writing anything, and enumerates the exact checks. This cleanly distinguishes it from siblings like save_ebay_variation_listing, get_ebay_variation_listing, and inspect_ebay_listings without needing to open any 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?

Explicitly routes the agent: 'Use save_ebay_variation_listing once ready is true,' and states the marketplace prerequisite ('needs a marketplace but not the owner's arming'). It stops short of contrasting with the read-side sibling get_ebay_variation_listing, so the when-to-use guidance is clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only behavior is established. The description adds useful context beyond annotations: it states the return format (summary rows with specific fields) and pagination structure, and implicitly warns that these are not full details by pointing to get_activity. No contradictions exist.

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?

Three sentences, front-loaded with the core action and resource, followed by return info and an alternative. Every sentence earns its place; zero waste. It is structured for quick scanning by an agent.

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

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

Despite having no output schema, the description specifies exactly what fields are returned (id, type, title, priority, dueDate, completed, assignee, linked lead/contact/company/deal, isOverdue) and the pagination shape. It also covers the main filter categories and points to the detail-fetching sibling tool, so an agent has enough context to invoke and interpret results 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 fully documents each parameter. The description merely groups the filters ('type/assignee/overdue/completion/linked-entity') without adding new details about parameter values, formatting, or relationships. This matches the baseline for high schema coverage.

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

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

The description uses a specific verb ('List') with a clearly defined resource ('this workspace's activities'), enumerates the activity types, and lists filtering dimensions. It also distinguishes itself from get_activity by noting that the latter returns full detail, so the purpose is unambiguous and differentiated 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?

The tool's usage context is explicit: it's for listing/filtering activities with pagination. It provides a clear alternative directive: 'Use get_activity to fetch one activity's full detail by id,' which tells the agent when a different tool is more appropriate. This counts as explicit 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'List' operation is consistent with that. The description adds the specific fields returned (id, name, description, website), which is useful behavioral context beyond the annotation. It does not disclose any edge cases like pagination or sorting, but for a zero-parameter catalog list the added field information is sufficient. No contradiction with annotations.

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

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

The description is a single, dense sentence stating the action, scope, and return fields, followed by a second sentence on how to use the output. Both sentences are purposeful, with no filler or redundancy. The most important information (what it lists) is front-loaded.

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 no parameters and a read-only list operation, the description provides the essential context: what it returns and how the results are meant to be used downstream. Given the annotations already convey safety, and the schema is empty, nothing critical is missing. The only minor gap is the absence of pagination or ordering information, but that's expected for a simple list 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 tool has zero parameters and the schema is empty, so there is nothing for the description to explain. Per the rubric, a zero-parameter tool receives a baseline of 4, and the description doesn't under-explain anything. It doesn't need to elaborate on semantics that don't exist.

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 ('List'), the resource ('this workspace catalog brands'), and enumerates the returned fields (id, name, description, website), making the tool's purpose unmistakable. It also ties the output to concrete downstream uses (brandId for create_product/update_product and as a search_products filter), which further clarifies what this tool is for. No sibling list tool appears to overlap, so distinction is clear.

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 explains a primary use case—obtaining brand ids to populate brandId fields in other tools—which is practical and concrete. It does not, however, explicitly state when not to use this tool or compare it with alternatives like list_categories or list_products. The context given is enough for an agent to infer that this is the go-to for brand listing, but without exclusions 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 already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds valuable behavioral context: it returns a flat array with specific fields, clarifies workspace-global scoping, and links to related operations. This goes beyond the annotations by explaining output shape and how the tool's results feed into other actions.

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, each contributes essential information. The first defines the action and output format; the second explains how to use the output. There is no filler, no repetition of the name or title, and the most important scoping detail is placed early. Exemplary 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 has no parameters and no output schema, the description fully specifies what the agent receives (flat array of categories with id, name, slug, parentId) and how to leverage it for downstream operations. Nothing an agent needs to call this tool correctly or interpret its result 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?

The tool has zero parameters, so the schema coverage is trivially 100%. The description correctly does not pretend to explain parameters. Per the calibration guideline, a baseline of 4 applies for tools with no parameters, and there is nothing more expected here.

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 ('List'), a concrete resource ('this workspace catalog categories'), and the exact output fields (id, name, slug, parentId). It also clarifies scope ('workspace-global, not per warehouse'), which distinguishes it from warehouse-related tools. This makes the tool's purpose unambiguous and easily differentiable 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?

The description gives clear guidance on how to use the output: a category id can be used as categoryId for create_product/update_product or as a search_products filter. It does not explicitly compare with alternative list tools, but the usage context implies when it would be relevant. It lacks explicit 'use this when...' or 'do not use when...' phrasing, but the guidance is actionable and specific.

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 rich behavioral nuance beyond the readOnlyHint annotation: the semantics of null observedAt, the meaning of presence, reconciliation cadence for Prom versus other channels, and the inclusion of unmatched ACTIVE products. This is exactly the kind of interpretation an agent needs to avoid misreading results.

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 clause earns its place: output fields, a subtle null-value caveat, refresh behavior, the unmatched-products report, and an explicit pointer to a sibling tool. The key purpose is front-loaded before adding necessary caveats.

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 one-parameter tool with no output schema, this description is remarkably complete. It explains what is returned, critical edge cases around observedAt and presence, refresh cadence, the unmatched-by-SKU list, and where to go for refusal explanations. An agent can invoke this correctly with minimal ambiguity.

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 platform parameter is already fully documented in the schema with an enum-like list of marketplace slugs and a pointer to list_marketplaces. The description reinforces that the tool is per-marketplace but adds no new parameter-level meaning beyond the schema, so 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 ('List') and a specific resource ('products that are on one marketplace'), and it enumerates the exact fields returned. It distinguishes itself from generic product-listing tools by emphasizing channel-specific listing data and the 'did not match by SKU' list.

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

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

It gives a clear use case: 'usually the answer when a push updated fewer products than expected,' and explicitly routes to check_channel_readiness for refusal reasons. It could more explicitly contrast with list_products or other listing tools, but the marketplace-specific framing and cross-reference provide solid guidance.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, non-open-world), and the description adds substantial context beyond them: per-channel readiness, destination, maxTextLength, the setup step needed when not ready, image rules, the workspace clock/timezone, and crucially publishingEnabled (whether the owner permits AI clients to publish or schedule). This is rich behavioral disclosure.

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 purpose and channel list before diving into return fields and the usage directive. The first sentence is very dense and long, which slightly hurts scanability, but nearly every clause carries distinct 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?

With no parameters, no output schema and annotations covering safety, the description fully compensates by enumerating what the call returns and how to use it. An agent has everything needed to call it and consume the result correctly.

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

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

The tool takes zero parameters, so the baseline of 4 applies. The description instead describes the shape of returned fields (ready, destination, maxTextLength), which adds helpful semantics though it is not parameter documentation.

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+resource ('List the social channels this workspace can publish posts to') and enumerates the exact channel types (Telegram, Instagram, Facebook, LinkedIn, Threads). An agent can distinguish it from list_content_posts or get_workspace_info without opening any 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 sequencing guidance ('Call it before create_content_post') and a constraint ('only target ready channels'), plus mentions building schedule_content_post times from the returned clock. It lacks an explicit contrast with the overlapping sibling check_channel_readiness, so routing among read tools is left partly implicit.

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

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

Annotations already cover the safety profile (readOnlyHint=true). The description adds real value beyond them by defining the three language sets and explaining the ISO 639-1 entry format, plus a behavioral constraint on downstream writes. It restates 'Read-only' rather than adding new safety context, so not a 5.

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

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

Dense but front-loaded with the core purpose in the first clause; the operational warning about translation writes is placed last where it belongs. Slightly long overall but every sentence carries distinct 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?

With no parameters and no output schema, the description fully covers what an agent needs: what the sets mean, the entry format, and the constraint on how results are consumed by downstream translation tools. Nothing material 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?

Zero parameters, so the baseline is 4. The description goes further by characterizing the returned entries (ISO 639-1 code with English name), which is output-shape detail rather than parameter 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?

States a specific verb (List) and resource (languages this workspace writes product content in) and disambiguates three sub-categories: base language, extra languages, and the offered set. An agent can distinguish it from sibling list_* tools without opening any 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?

Explicitly states when to call it (BEFORE any translation write), names the three dependent tools (upsert_product_translation, upsert_category_translation, upsert_brand_translation), and gives a hard exclusion rule: write only offered languages, never the base language as a translation.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read-only' merely restates that. However, it adds behavioral detail outside the annotations: strict newest-first ordering and a fixed 20-per-page window, which materially affect how an agent pages through results. No contradictions with 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?

Three dense sentences, front-loaded with scope and ordering, then filters, then routing to the sibling tool. Every clause carries load and there is no padding.

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 enumerating the returned fields and the status vocabulary, and it covers both filtering and the natural follow-up tool. An agent has everything needed to call and use it correctly.

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

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

Schema description coverage is 100%, so the schema already documents page, query, and status (including the enum meanings). The description restates the same information at roughly the same level of detail, adding no format or syntax guidance beyond the schema. 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 ('List the workspace's social posts'), plus ordering, page size, and the exact fields returned (id, working title, status, channels, times). It is clearly separable from get_content_post, which it names explicitly.

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

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

Explicit routing: use get_content_post for a single post's texts and per-channel results, and use this list to check what is already scheduled before planning more posts. It also names the two filter axes (status, partial title) that select this tool.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context by explaining the exact customer scope (won deal or delivered order) and the return format (summary rows plus pagination object), which goes beyond the annotations.

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

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

Three sentences: first states the action and scope, second lists return fields and pagination structure, third directs to get_customer for detail. Every sentence adds value, no filler, and the most important information is front-loaded.

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

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

Given the tool has 8 optional parameters but no output schema, the description fills the output gap by listing exact fields returned and pagination shape. It also communicates the customer definition and the alternative for detail-only use. This is complete for an agent to select and invoke the tool confidently.

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 every parameter already has detailed documentation. The description adds a high-level grouping ('filtered by health/lifetime-value/won-deal count') that maps to health, ltv, and wonDealsMin, but doesn't add new per-parameter meaning beyond what the schema provides. 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 clearly states 'List CRM customers' with a precise definition ('companies with a won deal or delivered order'), and specifies filtering, sorting, and pagination. It distinguishes itself from the sibling get_customer by explicitly pointing to that tool for detail retrieval.

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 clear context for when to use this tool (listing/filtering/sorting/paginating CRM customers) and explicitly names get_customer as the alternative for fetching a single customer's detail. It doesn't mention other alternatives like search_companies, but the guidance is sufficient.

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 readOnlyHint/destructiveHint/openWorldHint annotations, it discloses the caching model ('Reads the stored copy; a site never read before is read from eBay, and refresh true reads eBay now') and clarifies the semantics of derived fields like productCount and staleAssignments. This is meaningful behavioral context an agent would otherwise have to guess.

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?

Purpose and scope are front-loaded, and the sentence describing return fields earns its place given there is no output schema. It is dense and reads as one long run-on paragraph, but there is little outright waste.

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 correctly carries the burden of describing return values (listed fields, productCount, staleAssignments), plus usage routing and caching behavior. 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 description coverage is 100%, so both parameters are already documented in the schema, and the description largely restates them (refresh hitting eBay, omitting marketplaceId listing all sites). It adds no format or syntax detail beyond the schema, 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 (List) and resource (eBay shipping/fulfillment business policies) scoped to 'each eBay site the connection sells on', and enumerates the returned fields. It clearly distinguishes itself from the point-read sibling get_product_ebay_fulfillment_policy. An agent can tell exactly what this returns without opening any 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?

Explicitly routes the agent: 'Use a fulfillmentPolicyId from here with set_product_ebay_fulfillment_policy, bulk_set_ebay_fulfillment_policy or set_ebay_default_fulfillment_policy; for one product's policy use get_product_ebay_fulfillment_policy.' It names both the follow-on writes this feeds and the alternative for the single-product case, plus the refresh/stored-copy 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?

The annotations already declare read-only and non-destructive behavior, and the description complements this by detailing what the output contains (built-in plus custom, key/label/active state) and the effect of includeInactive on returned data. This adds meaningful behavioral context beyond the annotations.

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

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

Three sentences, each packed with relevant information and no redundancy. The main purpose is front-loaded, and the related-tool guidance is efficiently included without extra verbiage.

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 read-only list operation with one optional parameter and no output schema, the description fully covers purpose, parameter behavior, relation to sibling tools, and expected return contents. No gaps remain.

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

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

Schema coverage is 100% and the only parameter (includeInactive) is already described in the schema. The description reiterates the parameter's purpose ('Pass includeInactive to also return archived sources') but adds only the nuance that archived sources are excluded by default, which is a minor enhancement. 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 specifies the exact action ('List this workspace's lead sources') and the data returned (key, label, active state). It also distinguishes itself from sibling tools by referencing set_lead_sources and search_leads, making its purpose unmistakable.

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 tells when to use this tool vs alternatives: 'Use set_lead_sources to add or archive a source; use a source key here as the source filter for search_leads.' It also explains the conditional use of includeInactive for archived sources.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds valuable context by clarifying that it lists every marketplace in the workspace, includes sync errors and health indicators, and requires no arguments. No hidden side effects are suggested, and the description is consistent with 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 information-dense but efficient: the first sentence front-loads the resource and returned fields, the second states the use-case question, and the final sentence gives sibling routing. No filler or redundant restatement of the title.

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 carries the burden of explaining return content and does so thoroughly: setup state, health, last activity, sync errors, revenue per currency, leads, product counts, and pending reviews. It also covers scope, arguments, and alternatives, making it complete for an agent selecting and invoking this 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?

There are zero parameters and the schema is empty (100% coverage). The description adds the explicit statement 'Takes no arguments', which is sufficient. Baseline 4 is appropriate for a parameterless tool.

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

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

The description states a specific verb and resource: list every marketplace connected to the workspace. It enumerates the returned categories (setup state, health, sync errors, revenue, leads, product counts) and explicitly differentiates itself from get_marketplace, list_channel_products, and check_channel_readiness.

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 answers when to use this tool ('which channels do I sell on and is anything broken') and routes to alternatives for detail, products, and readiness checks. This gives an agent direct decision criteria without needing to inspect sibling schemas.

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 readOnlyHint and destructiveHint annotations, the description adds meaningful behavioral context: it returns summary rows rather than full objects, includes a pagination object, and orders results newest first. These are non-obvious behaviors the agent cannot infer from the schema 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?

The description is exactly two sentences, front-loads the primary purpose and scope, and devotes the second sentence to sibling routing. Every sentence earns its place with no filler or repetition of schema 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?

With no output schema present, the description compensates by specifying the return shape (summary rows and pagination object) and ordering. It covers the tool's scope, filtering capabilities, pagination, and the alternative for deeper detail, leaving no critical gap for an agent deciding to call this tool.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters thoroughly. The description adds minimal extra parameter meaning beyond mapping 'status/customer/created-date' to the filter parameters, which is not a significant enhancement over the schema. The baseline of 3 is appropriate here.

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 ('List'), a specific resource ('this workspace's orders'), and the key scoping constraints (status/customer/created-date, paginated). It also explicitly differentiates itself from get_order by noting that list_orders returns only summary rows while get_order returns full detail, making the distinction clear.

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 names the exact alternative, get_order, and states the condition under which it should be used ('to fetch one order's full detail'). This gives the agent explicit routing guidance and implicitly tells it not to use list_orders when full detail is needed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that stages are returned 'in order' and lists specific fields, which is useful but not extensive. It does not discuss permissions, rate limits, or pagination, but for a simple read-only list tool with good annotation coverage, 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?

The description is two sentences, front-loaded with the primary action and target, and every clause adds useful information. It lists output fields and gives explicit cross-tool references without fluff.

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 simple with no parameters and no output schema, so the description carries the burden of explaining return values. It fully specifies the fields and ordering, and also provides context on how the stage id is used elsewhere. This is complete for the tool's complexity.

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 tool has zero parameters, so schema coverage is trivially 100%. The description does not need to clarify parameters, and the baseline for no parameters is 4. It adds value by describing output fields, though that is more about return semantics than parameters.

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 specific verb 'List' with the resource 'pipeline stages' and scopes it to 'this workspace'. It enumerates the exact fields returned (id, name, kind, default probability, WIP limit, position), making the tool's purpose crystal clear and distinguishing it from sibling tools like configure_pipeline.

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