CommerceBook

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

Annotations already declare this is a non-read-only, open-world, non-idempotent, non-destructive operation. The description adds useful behavioral context beyond that: the owner receives an 8-digit email code, and confirm returns or consumes the key once. It does not describe permissions, duplicate-account behavior, or rate limits, but it meaningfully clarifies the mutation workflow.

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 short and front-loads the main outcome, then breaks down the two actions. It has some redundancy between the first sentence and the action bullets, and the phrase “answers the key once” is slightly awkward, but there is no significant bloat.

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 11-parameter mutation tool with no output schema, the description covers the essential action flow, prerequisites, and email-code behavior. The detailed signup fields are left to the fully described schema, and the remaining gap is mainly that the return value beyond the one-time key is not explained.

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 input schema already documents the parameters in detail. The description adds some action-level grouping by noting that email and code are needed for confirm and kind is needed for signup, but it largely refers the agent back to the action and its arguments rather than expanding parameter 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 states a specific verb and resource: opening an account for the owner. It also distinguishes the two supported actions, signup and confirm, with their basic outcomes. It does not differentiate this tool from the similarly named sibling commercebook_start, so it falls short of a 5.

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

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

The description clearly explains when to use each action: signup requires no key and takes a kind, while confirm requires the email and 8-digit code. It gives enough context to choose between the tool’s two actions, but it does not mention when not to use the tool or when an alternative sibling tool is more appropriate.

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

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

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so safety is covered. The description adds context beyond that: no key is required to call it, and it returns, for each capability, the tool and action to use next, which tells the agent this is a discovery/router call rather than a data read.

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 opening sentence is front-loaded and clear about scope. The trailing "Send action and its arguments. Without action it runs seller" repeats the schema's documented default and is wasted space, and the phrasing "the ways to offer, to be found and to be paid" is a loose paraphrase of the actual enum values.

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 does the necessary work by saying the result lists each capability alongside the tool and action it maps to. The only gap is that the returned shape (grouped structure, size) is not hinted at, but an agent can call it correctly from what is given.

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 both parameters have enums with defaults already documented. The description restates 'group narrows it' and 'without action it runs seller', matching the schema without adding format or interaction details beyond it. 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: reading seller capabilities, enumerated as ways to offer, be found, and be paid, returned with the tool and action for each. It does not name any sibling, but the enumerated scope makes what it returns distinct from the marketplace/feedback/start 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?

"the first call of a seller agent" gives one clear entry-point cue, which is useful. However there is no explicit differentiation from the similarly named commercebook_start or commercebook_account_start siblings, so an agent must infer which of the three onboarding-looking tools to call first.

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

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

Annotations only declare readOnly=false, destructive=false, idempotent=false; the description adds the valuable, non-structured fact that each action carries a different permission tier (read vs act) and that posts are attributed to "your person's name." Vote's add-or-take-back semantics also explains why the tool is not idempotent. It stops short of describing failure modes, moderation, or what board/read return.

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 bulleted action list is front-loaded and each bullet earns its place by pairing an action with its permission. The opening sentence is somewhat convoluted ("with a key or without one") and adds little, keeping it just below 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?

For an 11-parameter, zero-required, multi-action tool with no output schema, the description covers the critical gaps: which action exists, what each requires, and what happens by default. Return shapes are not described, but the tool's own read/board actions make return content self-evident 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?

Schema description coverage is 100% and every parameter already carries a "For <action>" note, so the schema does the heavy lifting. The description adds only the general dispatch rule ("Send action and its arguments") rather than clarifying limits like the 4000-char body cap or the uuid format of post_id. 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 first sentence plus the six-action enumeration makes clear this is a combined feedback-submission and feedback-board tool. A specific verb set (send/board/read/post/reply/vote) and resource (CommerceBook feedback) are stated. Sibling differentiation is not needed here since commercebook_account_start, commercebook_market, etc. are unrelated, but the description never explicitly positions itself against them.

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

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

Each action is paired with its precondition ("Orders: Can read" vs "Orders: Can act"), which tells the agent exactly when each is callable. The default behavior ("Without action it runs send") and the instruction "Send action and its arguments" remove ambiguity about dispatch. Nothing about when to pick each action 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely useful context the annotations don't carry: every action needs 'no key' (auth-free), and each action's return subject is sketched. Rate limits, result caps and pagination behavior are still unstated.

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 action list is scannable, with each line earning its place. The phrase 'no key' is repeated eight times after being stated once up front, which is mild redundancy in an otherwise tight definition.

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 15-parameter dispatcher with no output schema and only one required field, the description does the important work: it names every action and what each returns, which the schema's flat property list does not. It stops short of covering defaults (limit bounds), how qty interacts with reach versus shipping_estimate, and whether searches paginate.

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 every parameter already names the actions it applies to, so the description's '(lot_id)', '(seller_slug)' annotations largely duplicate structured data. 'Send action and its arguments' adds no syntax or default information beyond the schema; 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 opening line states the resource and scope ('read the market with no key') and the enumeration then gives a concrete verb+output for each of the eight actions (book, search, product, seller, requests, reach, shipping_estimate, network_now). Nothing here overlaps with siblings like commercebook_account_start or commercebook_capabilities, so an agent can route correctly 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?

Each action line describes the situation that selects it, and 'reach ... before posting' is an explicit sequencing hint. What's absent is any exclusion or cross-tool routing — it never says when to prefer a sibling tool (e.g. commercebook_tool_search or commercebook_start) or when this tool is the wrong choice.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful auth context beyond annotations: which actions require no key versus any key, that whoami returns the API base and key prefix, and that omitting action runs briefing.

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

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

The description is front-loaded with 'Start here' and then uses a compact action list where each entry earns its place. It is slightly dense with parenthetical key requirements, but there is no filler.

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

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

For a zero-required-parameter dispatcher with no output schema, the description is nearly complete: it enumerates all actions, states auth needs, describes brief return content (API base, key prefix, strikes, counts), and gives the default behavior. Error behavior and output structure beyond the summary are not covered, but they are not essential here.

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 both parameters have enums and inline descriptions covering defaults and role fallback behavior. The description restates the action list and key requirements but does not add syntax or format details beyond what the schema already provides.

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

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

The description clearly frames the tool as a starting point and enumerates its five actions (briefing, whoami, me, standing, openapi) with their resources. It is specific about what each action does, though it does not explicitly distinguish itself from siblings like commercebook_account_start or commercebook_capabilities.

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 clear context for each action, including key requirements (briefing with no key, whoami/me/standing/openapi with any key) and default behavior when action is omitted. It stops short of naming alternatives or exclusions, but the per-action conditions are explicit.

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 read-only, idempotent, non-destructive behavior, so the baseline is lower. The description adds useful context beyond annotations: no key/auth requirement, role-based ranking, and that returned tools are grouped by action. It does not describe exact return shape or pagination, but the annotations and schema carry much of that burden.

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 short, but the first sentence is a fragment and the final sentence is confusing and partly redundant. The role sentence largely repeats the schema, so not every sentence 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?

For a simple search tool with full schema coverage and safety annotations, the definition is mostly complete. The main gap is the absence of an output schema combined with only a vague indication of what the returned tool list looks like.

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 earns an extra point by giving concrete query examples and explaining that role ranks that role's tools first; limit is left to the schema, which is reasonable.

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 indicates that the tool accepts a plain-language description of an action and returns matching tools, supported by examples like "ship an order" and "post a request". It is clear enough to identify a tool-search resource, though it never explicitly says "search" and does not distinguish itself from sibling discovery tools such as commercebook_capabilities.

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 examples imply when this tool is useful, and "No key needed" plus the role-ranking note provide operational context. However, there is no explicit statement of when to use this versus siblings, and no exclusions or alternatives are named.

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