CommerceBook

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

Goes well past the annotations by disclosing rate limits (20 notes per address per day without a key), what changes with a key (recorded against the key and on the owner's ledger), and the downstream effect (a human reads every note; the 'What is coming' list is shaped by them). That is exactly the behavioral 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?

Three dense sentences with no filler, each contributing purpose, motivation, or constraints. The 'POST /feedback' prefix is slightly gratuitous protocol detail, but it front-loads the action effectively.

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 4-parameter write tool with no output schema, the description covers intent, field meaning, limits, auth behavior, and consequence. The only modest gap is what a successful submission returns, which an agent might want confirmed.

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 only 25% (just 'about' is documented), so the description carries real weight: it explains that 'about' can be a tool or page, maps what_happened and what_would_help, and confirms rating is optional with a 1–5 range. It does not add format or length guidance for the two free-text fields beyond what the schema states.

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 ('POST /feedback: a note on a tool or a page, what happened and what would have helped') that is unambiguous, and the action is clearly distinct from every sibling tool, which are all market/network data reads.

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

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

Gives clear context for when to use it: when an agent has something to report about a tool or page and what would have helped. It doesn't name explicit exclusions or alternatives, but no sibling competes for this purpose, so the gap is minor.

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 the description adds substantial behavior the schema cannot convey: a 15-minute cache, no API key required, null when there are no fills, and the trust rule that seller reliability shows a raw count until 10 orders then a percent (the {n, of, rate, shown_as} shape). That is exactly the extra context an agent needs to interpret results without being misled.

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 endpoint and the one-line purpose, then segments behavior by named block (supply/demand/fills_30d/sellers), so the dense text is navigable. It is on the long side and the sentences are run-on with semicolons, but every clause carries operational meaning — cache, null handling, zero-category semantics — rather than 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?

With zero parameters and no output schema, the description carries the entire burden of explaining return values, and it does: field names, units, null semantics, categorical completeness, and the derived-reliability rule. An agent can call this and interpret the response correctly without further documentation.

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 no parameters, so the baseline is 4. The description still clarifies the meaning of values inside the response (from_unit_cents starts at one unit, ceilings expressed as bands with no buyer identified), which offsets the absent input surface.

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 concrete resource (GET /market/book) and enumerates the four content blocks it returns — supply, demand, fills_30d, sellers — so an agent knows exactly what the payload covers. It does not explicitly contrast itself with the narrower siblings (market_intents, market_search, market_lot, market_seller), leaving the agent to infer that this is the aggregate snapshot.

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?

Usage is only implied: the breadth of the response (everything by category, zero-count categories included) hints that this is the landscape/overview call, and the zero-reads-zero rule is framed as a discovery aid for finding quote and post opportunities. There is no explicit 'use this when… instead of market_search/market_intents' statement.

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 the description adds meaningful traits beyond them: buyer identity is withheld, ceiling is a band when the buyer hid it, categories reports zero when empty, and supplying a key adds the member's own requests in every state. It doesn't discuss pagination or response size, 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?

It is front-loaded with the route and the core purpose, and every clause carries information (returned fields, hidden ceiling, category behavior, key behavior). The nested parentheticals make it somewhat dense and run-on, which costs a 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 enumerates the returned fields and explains the two edge cases a caller must expect (masked ceiling bands, zero-count categories). For a two-parameter read tool, the only minor omission is limit behavior, which is not decisive.

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 50%: category is documented in the schema and reinforced in the description ('category narrows it'), but limit has no description in either place, leaving the 1–200 bound and its truncation behavior unexplained. The description adds some value over the schema but does not compensate for the gap.

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 resource and scope: 'every open public request ... with its title, category, quantity, ceiling, state, expiry and open quotes,' and frames it as 'the demand side of the book.' This implicitly distinguishes it from commercebook_market_book, but no sibling is named explicitly, 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?

'category narrows it' and 'with a key the answer adds mine' give some usage context, implying when to add a category filter or authenticate. However, there is no explicit guidance on when to use this versus commercebook_market_search or commercebook_market_book, and no exclusions are stated.

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 establish read-only, idempotent, non-destructive and closed-world behavior, so the remaining burden is low. The description still adds real value beyond them by stating 'No key needed' (no authentication required), that the listing is 'public', and by enumerating what content comes back: count, condition, last-confirmed date, photos, shipping, active offers and shipping states.

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 is a single sentence, front-loaded with the HTTP path and the core purpose, and every clause (offers, shipping states, no key) carries information. The parenthetical enumeration of fields is dense but not wasteful.

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 one required parameter, no nested objects, no output schema and full annotation coverage, the description is nearly complete: it tells the agent what to supply, what auth state is needed, and what data the response carries. Only the return shape's exact structure is left unspecified, which is acceptable given there is no 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 coverage is 0% but there is only one parameter, and the schema itself supplies the uuid format and an explicit regex pattern. The description identifies lot_id as the identifier of the public product being fetched, which is a modest addition over the schema; with a single well-typed parameter this is adequate rather than rich.

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

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

The description names a concrete verb and resource ('GET /market/lots/{id}: one public product') and even clarifies it returns the listing as a product page presents it. It does not explicitly contrast itself with siblings like commercebook_market_search or commercebook_market_book, so it stops short of a top score.

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?

Usage is only implied: the tool requires a lot_id, so an agent infers it should be used when a specific product identifier is already known and search is not needed. There is no explicit when-to-use statement, no exclusion rules, and no mention of when to prefer commercebook_market_search.

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

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

Annotations cover safety (readOnly, idempotent, non-destructive), and the description adds substantive behavior beyond them: whole-word matching with plural-only stemming ("stretch never matches stretcher"), relevance-then-price sort order, the tiered pricing model with price_mode/price_schedule/price_text and the unit_price_cents-at-quantity rule, plus "No key needed" for auth. This is exactly the extra context annotations cannot express.

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 operation and resource, and every clause carries usable information with no filler. The trade-off is density: the second sentence is a long run-on enumerating return fields and pricing modes, which is harder to scan than a bulleted structure would be.

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

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

With no output schema, the description carries the burden of documenting return values, and it does — offer id, price, quantity available, minimum, fulfillment, seller, product URL, plus the tiered-pricing fields. Combined with the schema and annotations, an agent has everything needed to call 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?

Schema coverage is only 43%, so the description has to compensate, and it largely does: q matching semantics, category as an exact key sourced from commercebook_market_book, prices in cents per unit, state as ship-to, and condition. It never clarifies the `limit` parameter (bounds 1-100) or states the default page size, leaving a small gap.

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 ("GET /market/search: the products for sale on CommerceBook") and enumerates the searchable fields, so it is immediately distinguishable from siblings like commercebook_market_book (category listing) and commercebook_market_intents (requests). No ambiguity about what comes back.

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 usage context (searching for-sale products by text, category, price, ship-to state, condition) and routes the agent to commercebook_market_book for resolving category keys. It stops short of explicit when-not-to-use-this guidance versus market_intents or market_lot, but the context is unambiguous.

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 a safe read, but the description adds real behavioral context: the data is computed and 'the seller writes none of it', no key is required, and the rate fields behave differently by threshold ('shown_as, a count until it is built on 10 orders, then a percent'). That threshold rule is exactly the kind of trait an agent could not infer elsewhere.

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 endpoint and the resource summary, and nearly every clause carries information. It is dense with semicolon-separated parenthetical lists, which makes it harder to scan than necessary, but little is genuinely 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 correctly takes on the burden of explaining return contents in detail, including the tier values and the count-vs-percent threshold. Minor gaps remain, such as error behavior for an unknown slug and whether the live products list is paginated or truncated.

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 parameter's schema description already explains it as the seller_slug of a search item or product. The description restates that same meaning without adding format, edge-case, or lookup guidance 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?

States a concrete verb and resource ('GET /market/sellers/{slug}') and enumerates exactly what the computed record contains: tier, 90-day/all-time delivery metrics, ratings, live products, storage locations, and buyer-facing terms. This is unmistakably different from the list/search 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?

Usage is implied by 'seller_slug of a search item or a product', which hints the slug is obtained from a search result, but no sibling is named and there is no explicit when-to-use or when-not guidance (e.g., versus commercebook_market_search for discovery).

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 provides important behavioral limits/traits like the 15-minute caching period. Since annotations already confirm it is read-only and idempotent, the description provides unique, valuable operational context.

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

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

The description is perfectly front-loaded and highly efficient. It uses the HTTP method and path in the first part, followed by detailed scope and behavioral constraints, achieving maximum information density.

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

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

The description covers the core functionality (what data), the scope (7 days/this month), the technical entry point (no key), and the operational constraints (15-minute cache), making it complete despite 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?

Since there are zero parameters (schema coverage is 100%), the baseline is 3. The description adds minor value by indicating no key is needed, which relates to the input requirements even though the schema is empty.

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

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

The description explicitly states what is retrieved: 'verified members, leads listed in the last 7 days, prices posted and savings confirmed this month.' It uses a direct verb ('GET') and specifies the resource scope, clearly distinguishing it from other sibling tools which are generally prefixed 'commercebook_market'.

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 notes that 'no key needed,' which is critical usage information that might differentiate this from other API calls that could require authentication, thereby guiding usage immediately.

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, idempotentHint, and non-destructive behavior. The description adds that output differs by key presence, but the phrase 'briefing of its own kind' is opaque and it omits details such as how the key is supplied or what the response format looks like.

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

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

The description is a single, front-loaded sentence with no filler. The content list is dense but every phrase contributes information about what the briefing contains.

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 no-parameter, read-only tool with no output schema, the description adequately says what content is returned. It still leaves ambiguity around the key mechanism and the exact return format, which matters for an agent deciding how to invoke it.

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

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

The input schema has zero parameters, so parameter semantics are inherently minimal and the baseline is 4. The description references a key, but since no key parameter exists in the schema, this is not a parameter-semantics gap.

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 identifies the resource (GET /instructions) and enumerates the briefing content it returns, which is clear enough to tell it is an instructions/help endpoint. It does not explicitly differentiate itself from siblings such as commercebook_feedback, but the purpose is not vague.

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 no-key versus key distinction implies usage: call without a key for the buyer briefing, with a key for a role-specific briefing. However, it never states when to use this tool instead of siblings like feedback or signup, so the guidance remains 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 declare readOnly, idempotent, non-destructive, and openWorld=false. The description adds genuinely new behavioral facts: no API key is needed and the response is cached for 15 minutes, which matters for staleness expectations. It does not discuss rate limits or error behavior, hence 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?

Two short clauses, zero filler. The identity/compatibility statement is front-loaded and the payload plus caching detail follow immediately. 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?

With no parameters and no output schema, the description carries the burden of telling the agent what comes back, and it does: verified members, 7-day leads, monthly prices and confirmed savings, plus auth and cache behavior. Only the shape/format of the response (fields, pagination) is unspecified, which keeps it from a 5.

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 nothing for the description to disambiguate and the baseline of 4 applies. The description correctly spends no words on parameters and instead describes the fixed payload.

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 precisely what the tool is – the legacy alias of commercebook_network_now – and immediately after what it returns (verified members, recent leads, prices, savings). The sibling relationship is explicit, so an agent can tell it apart from commercebook_network_now 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?

"Kept so agents that call it keep working" tells the agent this exists for backwards compatibility, which implicitly routes new usage to commercebook_network_now. It stops short of an explicit "prefer the new name for new code" instruction, so a small inference is left to the agent.

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 (readOnlyHint=false, destructiveHint=false), and the description adds genuinely useful behavior the schema cannot convey: the key is 'shown once', the account is created as a side effect, and money operations still require the owner's Stripe steps. That last point usefully scopes what this tool does not accomplish.

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 is a single front-loaded block with no filler, but the phrasing is awkward ('answers the key', 'the member's document') and the Stripe sentence sits at the end with only loose relevance to confirming signup. Tighter wording would make the key-collapse warning land harder.

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 must describe returns, and it does: the agent link key, the agent link, and the member's document. It also gives the follow-up auth step. The only gap is what happens on an invalid or expired code.

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 load and it largely does, explaining that both inputs come from the owner's email and that the code is the 8-digit value. It doesn't clarify format or error behavior for a malformed or expired code, but both parameters have usable 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 the concrete effect ('Makes the account') and the exact inputs ('the email and the 8-digit code'), which is more than the title's vague 'Confirm the account'. It is distinguishable from signup_start, but the verb+resource framing is buried inside a URL-ish prefix rather than stated cleanly.

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 prerequisite is implied ('the code the owner read in the email') and the follow-up is explicit (reconnect with Authorization: Bearer <key>), but it never names signup_start as the preceding step or says when this tool should not be used. Usage is inferable rather than guided.

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, the description discloses key behavioral traits: an 8-digit code is emailed with no link, the code expires in 30 minutes, there is a rate limit of three starts per email per day, and the key starts read-only. These details are crucial for correct invocation and are not present in the structured annotations.

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

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

The description is dense but front-loaded with the endpoint and purpose, and every sentence carries useful behavioral or sequencing information. It could be slightly more structured (e.g., with bullet points), but it is appropriately sized for the tool's complexity.

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

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

Given no output schema and rich behavioral requirements, the description covers the initiation step, rate limits, email behavior, kind-specific requirements, and the explicit next step. An agent has enough information to call the tool and proceed to signup_confirm without 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?

Despite only 44% schema coverage, the description clarifies the most consequential parameters: it explains the kind enum (warehouse, seller, buyer), notes that a buyer's company is optional and no address is asked, and specifies that a warehouse provides a street address. It does not cover city, state, sqft, or services, but it compensates well for the critical conditional requirements.

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 (POST /signup/start) and resource (open a CommerceBook account), and it distinguishes the step from the sibling signup_confirm by describing the flow. An agent can tell exactly what this tool initiates.

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 clear sequencing ('Then ask the owner for the code and call signup_confirm') and explains the kind choices, but it does not explicitly state when not to use the tool (e.g., if an account already exists). The usage context is clear, though not exhaustive.

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