SoldStack

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

Annotations already declare readOnly, idempotent and non-destructive, but the description adds genuinely new behavior: a concurrency/busy lock with a retry-after delay, the fee deduction applied before judging, and region-dependent currency and fee treatment (USD vs CAD). That is meaningful context beyond the annotation block.

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 outcome and its basis are front-loaded in the first sentence, followed by a compact parameter line-list, each entry earning its place with an example or default. Slightly long but 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?

With no output schema, the description does communicate the result shape (a decision plus reason) and covers retry behavior, fee handling, and regional variants. It is comfortably complete for a two-required-parameter decision tool, with only the size/condition filter semantics left to the sibling 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 0%, so the description carries the full burden, and it defines query format with an example, explains cost as the acquisition price in USD, gives min_profit's default and meaning, and enumerates source values with their currency implications. Only size/condition are left unexplained beyond a pointer to sold_comps.

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 decision outcome (buy, maybe, pass with reason) judged from sold comps after Poshmark's fee, which is far more than a restatement of the name. It also distinguishes itself from the sibling sold_comps by tying its size/condition filters to that tool rather than duplicating 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?

It gives concrete operational guidance: call for one item at a time, and if it reports busy, wait the stated seconds and retry. It also implicitly positions sold_comps as the raw-data counterpart via 'same filters as sold_comps', but never states explicitly when to prefer this tool over sold_comps.

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

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

With readOnlyHint/idempotentHint/destructiveHint already declaring a safe, repeatable read, the description still adds real behavioral context: a busy/backoff response the caller must handle, the ~10s uncached cost and 4-page read for deep=true, that deep reads in relevance order, and that source=poshmark_ca returns CAD prices and fees. It does not describe pagination limits or the shape of the returned stats object, but the annotations carry the safety profile and the description goes beyond 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 lead sentence front-loads the returned statistics before any parameters, and the rest is an efficient parameter-by-parameter block. It is long, but nearly every clause adds actionable detail (defaults, ranges, edge cases) rather than filler; minor tightening is possible but nothing is clearly 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 and 12 parameters, the description must explain both the return payload and the inputs, and it does: it lists every statistic returned and documents each parameter. An agent has enough to construct a valid call and interpret the response without opening the 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 0%, so the description carries the full burden for all 12 parameters, and it does: query format with examples and the kids'-clothing caveat, size exclusion warning, condition accepting plain words or exact grades, days range 1-365 with the relevance-sorting rationale, limit default 10 and 0-50 bound, comma-separated exclude_seller and department semantics, include_removed explaining removed_reason, and source currency behavior. This compensates completely for the undocumented 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 first sentence gives a specific verb+resource ("what an item actually sold for on Poshmark") and enumerates the concrete outputs: median sold price, p10-p90 range, days to sell, seller net after fees, price by condition, confidence rating, and matching sales. That is far more specific than a restated title. It stops short of a 5 only because it never names or contrasts with the sibling tool buy_or_pass, so the routing distinction has to be inferred from the name.

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 sets operational context ("call it for one item at a time") and a failure path ("if it reports busy, wait the given number of seconds and call again"), plus per-parameter usage counsel such as leaving size out unless the user named one and using days to keep prices recent since Poshmark sorts by relevance. It lacks any explicit when-not-to-use or alternative-tool comparison against buy_or_pass.

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