World Poll

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

With no annotations, the description carries the full burden; it usefully discloses that no payment or unlock_token is needed, that 409 occurs during pending_payment, and that answer bodies aren't sent to callback_url. It omits auth requirements, idempotency/re-submission behavior, and what happens to ask state, leaving meaningful behavioral gaps.

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 action, but it opens with the opaque "Hold/relay step 4", and the trailing pricing fragments ("Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.") partly duplicate "No payment" and read as protocol chatter rather than guidance for this call.

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 and no annotations, so the description must cover both behavior and inputs, yet it leaves all five parameters undocumented and omits auth and repeat-submission behavior. Only the error/precondition side is addressed; for a 5-param tool this is substantially incomplete.

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

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

Five parameters with 0% schema description coverage, and the description explains none of them — not body, ask_id, source, confidence, or source_note. The agent gets no semantic guidance for any input beyond what the bare type/enum declarations show.

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?

"Submit a free answer to an open ask" is a clear verb+resource, but the leading fragment "Hold/relay step 4" is cryptic without external context and the description never distinguishes this from the sibling submit_answer, so an agent can't confidently route between the two.

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 real preconditions: call after unlock.completed, and HTTP 409 while the ask is pending_payment. It states the free/no-token condition clearly but never names submit_answer as the alternative for the different workflow, so routing guidance is incomplete rather than absent.

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

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

With no annotations, the description carries the full behavioral burden and does so richly: it discloses return shape, one-time callback_secret, callback events and signatures, Stripe test mode, TTL defaults and maximums, USD-only Checkout, hidden samples, and post-payment lock states. This is far beyond what the schema alone conveys.

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 excessively long and includes details irrelevant to this tool, such as poll unlock pricing, catalog listing endpoints, and duplicate cost statements. While it is loosely structured into steps, the signal-to-noise ratio is poor and the core invocation information is buried.

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

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

Given the complex multi-step payment workflow, no annotations, and no output schema, the description is largely complete: it explains the return object's top-level fields, callback behavior, and follow-up calls. It falls just short of 5 because some noise and ambiguity remain, and nested ask object fields are not described.

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 repeats most parameter details already present in the schema and adds little new semantic information, aside from noting that deposit_cents and body are rejected, which is only marginally useful 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 names the specific action: 'Post an ask ... and start checkout,' and identifies the resource (ask). It distinguishes downstream steps from answer_ask and get_ask, though the opening 'Hold/relay step 1' and 'Same call as hold_ask and relay_ask' slightly muddle whether this is an alias or a distinct creation call.

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 implies usage through a detailed step-by-step payment workflow, but it never explicitly states when to choose create_ask over hold_ask or relay_ask, only that it is 'the same call.' No when-not or exclusion guidance is provided, leaving the agent to infer the selection context.

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

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

With no annotations, the description carries the full burden and does well: it discloses Stripe test-mode behavior (token reads results only after payment), that mock mode is already paid, that currency is fixed to USD, adaptive pricing is off, and that omitted payer_type defaults to agent. It omits auth/permission requirements and idempotency, keeping it short of 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?

The critical behavior and return info is front-loaded, but the fragmentary pricing sentences ("Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.") repeat the opener and read as taglines rather than invocation guidance, diluting focus.

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 usefully enumerates the return fields and the mode-dependent token behavior. Combined with the payer_type default, an agent has most of what it needs, though the missing when-to-use routing against siblings leaves a 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 0%, so the description must compensate. It adds meaning for payer_type by stating the default is "agent" when omitted, but gives no explanation of what slug is or what form it takes, leaving the required parameter undocumented in both schema and 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?

States a specific verb and resource ("Start a $1 poll unlock") and describes the return shape (url, mode, unlock_token), which helps distinguish it from sibling unlock tools. It is clear but not explicitly differentiated from unlock_ask/unlock_poll.

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

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

No indication of when to choose this tool over the many sibling unlock/catalog tools. It explains mode behavior but never states the conditions or alternatives under which an agent should call create_checkout rather than unlock_poll or unlock_ask.

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

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

With no annotations, the description carries the full burden and does well: it discloses that an un-paid unlock returns locked=true with omitted answers, that this is a normal result rather than a 402, and that invalid tokens yield a 401. Pricing tiers are also noted. It omits auth requirements and rate limits, keeping it short of 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?

Very short and front-loaded, but written as telegraphic fragments ('Poll unlock $1. Asker posts $1–$5...') whose connection to the read operation is unclear. Pricing sentences may not earn their place in a tool description focused on invocation.

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-annotation, no-output-schema read tool, the description covers the important behavioral outcomes (locked state, 401 errors, token sourcing). It does not describe the answer payload shape, but overall it is enough 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?

Schema coverage is 50%: unlock_token has its own schema description, ask_id has none. The description adds sourcing detail for unlock_token (create_ask / callback) and reinforces the anti-scraping warning, but ask_id's meaning is left to the schema alone, so it only partially compensates for the coverage 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 clear verb+resource: 'Read an ask.' The 'Hold/relay step 5' prefix signals workflow position but is cryptic without prior context. It distinguishes itself implicitly from unlock_ask by describing reading with a token, though it never names the sibling directly.

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 invocation guidance: pass unlock_token from create_ask or the unlock.completed callback, and do not scrape the success URL. However, it never states when to use get_ask versus sibling unlock_ask, nor any prerequisites or ordering beyond 'step 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?

With no annotations, the description carries the full burden and does well: it discloses the auth model (unlock_token vs paid key), exact error semantics (402 vs 401, and that an unpaid token is an error rather than a locked flag), and pricing. It stops short of describing return structure, pagination, or whether results are immutable once unlocked, so it is strong but not exhaustive.

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 telegraphic sentences are short and the core requirement is front-loaded, but the pricing lines ('Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.') are tangential noise for an agent trying to invoke the tool and dilute the signal.

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

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

For a two-parameter, no-annotation, no-output-schema tool, auth and error behavior are covered well, and the answer_count/aggregates.count hint partially describes the return. Missing pieces are the meaning of slug, the lock/pay flow relative to sibling tools, and any return-shape detail, leaving it adequate but incomplete.

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

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

Schema coverage is 0% and only one of two parameters (unlock_token) is explained — the description clarifies that it is optional when a paid key is used, which is meaningful given the schema marks only slug required. The slug parameter is never described, so the description does not fully compensate for the coverage 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 says it returns 'aggregates after pay' and that answer_count mirrors aggregates.count, which hints at the resource, but 'aggregates' is never defined and the resource is not named in a way that distinguishes it from get_ask or unlock_ask. An agent can infer this is a post-unlock results reader but must guess at the distinction 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?

It states the prerequisite (unlock_token or a paid API key) and the failure modes (402 for unpaid token, 401 for missing/invalid credentials), which tells the agent when the call will succeed. However, it never contrasts itself with alternatives such as unlock_ask, unlock_poll, or get_ask, so the routing decision 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?

With no annotations, the description carries the full burden and does so richly: it discloses callback_secret is returned once, the X-World-Poll-Signature header, the unlock_token absence from the success URL, the 409 pre-payment error, event payload contents, and Stripe test card. This is exactly the kind of behavioral context an agent needs for a payment-gated mutation tool.

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

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

The critical purpose and alias relationship are front-loaded, but the body becomes a dense stream of facts with redundancy — USD/adaptive-pricing-off appears both here and in the payer_type schema description, and the closing '$1–$5 / $1 / free' recap repeats pricing already stated. It survives as viable but wastes space on 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?

With no output schema and no annotations, the description fills most gaps by enumerating the flat return fields (url, mode, unlock_token, callback_secret, ask) and describing async callback behavior and failure modes. It does not detail the contents of the nested 'ask' object, leaving a minor hole for a tool with no structured output contract.

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 genuine disambiguation beyond the schema: 'the asker post field is price_cents, not deposit_cents', 'detail, not body', and 'unknown fields are rejected'. These naming traps are the highest-value additions an agent could get.

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 model ('Pay now, collect answers later (hold/relay)') and explicitly identifies itself as an alias of create_ask, which is useful for distinguishing it from siblings. The core purpose is clear even though the opening is compressed with pricing detail. It stops short of a clean one-line verb+resource framing.

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?

Lays out the full workflow sequence: pass callback_url, wait for unlock.completed, then answer_ask, then get_ask, and notes that before payment get_ask is locked and answer_ask returns 409. It names related tools but does not explicitly say when to prefer hold_ask over relay_ask or create_ask beyond calling itself an alias.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: asks with zero answers are omitted, sample asks (by is_sample or specific titles) are filtered unless include_samples is true. It does not mention auth requirements or ordering, but the filtering/omission semantics are unusually well documented for an annotation-free 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 pricing facts are stated two or three times ('Poll unlock $1. Asker posts $1–$5. Reader unlock $1' appears near the top and again at the end), and field-pricing musings interleave with the actual listing behavior. It is repetitive and not front-loaded around what the call does.

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 no annotations, the description does describe the return shape (topics plus items, with inventory seed/operator/product) and names relevant response fields (price_cents, unlock_cents, deposit_cents, reader_unlock_cents). It conflates pricing meaning with data shape, but an agent has enough to interpret the response.

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

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

The single parameter include_samples is undocumented in the schema (0% coverage), so the description must compensate. It does: sample asks 'are omitted unless include_samples is true,' which fully explains the parameter's effect beyond the bare boolean type.

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 gives a clear verb+resource ('List every topic on the buyer shelf') and even enumerates what a topic contains (seed polls, operator demos, the paid-ask product). However, the core purpose is quickly buried under pricing economics, and it doesn't sharply distinguish this listing from siblings like list_polls or list_open_asks beyond one routing sentence.

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 offers one explicit route ('Call list_open_asks to answer those') for zero-answer asks and explains when sample asks appear (include_samples). But it never states when to prefer this tool over list_polls or list_open_asks generally, leaving usage largely implied.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it explains the awaiting_answers flag semantics, discloses that reader unlock returns HTTP 409 while the flag is true, and documents that sample asks (is_sample, dogfood / WP Integrator / WP Buyer titles) are filtered out. It stops short of stating pagination/ordering or read-only character, so not a full 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?

The critical routing and gating information is front-loaded, but the trailing pricing sentences ('Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.') are tangential to a list tool and belong with unlock_ask/poll rather than here. These dangling cost fragments dilute 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?

There is no output schema, so the description must describe return values, and it does via the awaiting_answers field semantics and the row-source equivalence to GET /api/asks. Combined with the filtering rules and sibling routing, 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?

The tool takes zero parameters, which sets the baseline at 4; there is no input to describe and schema coverage is moot. The description instead usefully characterizes an output field (awaiting_answers), which is a bonus rather than a parameter explanation.

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 open asks for answerers, including ones with zero answers') and pins down scope precisely, distinguishing itself from list_catalog (rows 'not on list_catalog') and confirming parity with GET /api/asks. An agent can tell exactly what this returns without opening anything else.

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: 'Answer those with answer_ask for free' and 'Do not call unlock_ask until awaiting_answers is false,' naming the sibling tools and the gating condition. Both the when-to-use and when-not-to-use cases are spelled out, including the 409 consequence of ignoring it.

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

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

With no annotations, the description carries the full burden. It does disclose a real behavioral trait — the pricing model (poll unlock $1, asker posts $1–$5, reader unlock $1, answers free) — which is genuinely useful economic context. But it omits return shape, pagination, and the safe read-only nature of a list 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?

It is short, and the lead sentence is front-loaded and earns its place. But the mid-section devolves into cryptic fragments ('bathroom-minutes, sleep-hours, and commute-minutes are seed sample SKUs, not the product') whose relevance is unclear, so not every sentence clearly 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 zero-parameter list tool with no output schema, the essentials (purpose, teaser count, pricing) are mostly present. Still missing are what a poll entry actually contains and any listing limits/pagination, leaving the agent without a full picture of 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?

The tool takes zero parameters, so there are no per-argument semantics to document and the baseline is 4. The description correctly adds nothing spurious about arguments.

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 sentence states a clear verb+resource ('List polls with a teaser count'), which is enough for an agent to know what the tool returns. However, the remainder drifts into pricing and an obscure seed-SKU clarification rather than sharpening the purpose or contrasting cleanly with siblings like get_results or unlock_poll.

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 line 'Use list_catalog to see asks too' is a weak routing hint toward a sibling for a related-but-different resource, implying when to reach elsewhere. It stops short of any when-to-use/when-not conditions or prerequisites, leaving usage largely 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?

No annotations are provided, so the description carries the full behavioral burden and does: return shape (flat url, mode, unlock_token, callback_secret, ask), callback_secret shown once, signature header on callbacks, test-mode card, that the success URL omits unlock_token and should not be scraped, that event payloads exclude answer bodies, HTTP 409 pre-payment, USD-only with adaptive pricing off, and unknown fields rejected.

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 dense with zero filler sentences, though it reads as a run of terse fragments and repeats the USD/adaptive-pricing constraint already in the payer_type schema description. Trimmed slightly it would be easier to scan, 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?

There is no output schema, and the description compensates by naming the returned fields and their one-time semantics, plus the payment lifecycle, event names and payload contents, and the locked/409 states. 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%, so the baseline is 3, but the description adds real disambiguation beyond the schema: price_cents is the asker-post field and deposit_cents is rejected, detail is the optional text and body belongs to answer_ask, and unknown fields are rejected. Those are naming pitfalls an agent would otherwise hit.

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 a specific verb+resource ('Pay now, collect answers later (hold/relay). Deposit $1–$5.') and identifies the tool as 'Alias of create_ask', which lets an agent place it among siblings. It stops short of explaining why an agent would pick relay_ask over create_ask, so differentiation is implied rather than argued.

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 concrete operating sequence: pass callback_url, wait for unlock.completed, then answer_ask, then get_ask, and it states the pre-payment state (get_ask locked, answer_ask returns HTTP 409). What's missing is an explicit when-to-use-this-vs-a-sibling rule; the 'alias' framing leaves the create_ask vs relay_ask choice to inference.

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

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

With no annotations, the description carries the full burden. It usefully discloses that numbers are aggregated while strings, booleans, and null are stored only, which is real behavioral context. However, it omits auth/permission requirements, reversibility, and rate limits — gaps that matter for a write 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 opening sentence is well front-loaded, but the pricing tail is a fragmented staccato of telegraphic clauses ('Poll unlock $1. Asker posts $1–$5...') that adds bulk without clarifying invocation.

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 annotations, no output schema, and partial parameter coverage, the definition gives only aggregation behavior. It leaves out authorization, error/duplicate handling, and the role of the source param, so it is adequate but not 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 coverage is only 33%: slug and source have no descriptions. The description reinforces the value-typing behavior already documented in the schema, but adds nothing for slug (scope/what a slug is) or source (human vs agent), leaving two of three params under-explained.

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: 'Submit a free numeric (or JSON) answer to a poll by slug.' This is clear, but it does not differentiate from the very close sibling submit_poll_answer, which an agent could easily confuse it with.

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 trailing sentences ('Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.') convey cost, not when-to-use guidance or alternatives. Nothing tells the agent when to pick this over submit_poll_answer or answer_ask.

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

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

No annotations exist, so the description bears the full burden of behavioral disclosure. It conveys cost context (poll unlock, asker posts, reader unlock, free answers), which is useful, but omits mutation/side-effect behavior, authentication needs, and error handling.

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

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

Purpose is reasonably front-loaded, but the text is bloated with repetitive, tangential pricing copy: 'Answers are free' appears twice, and the unlock/posting price fragments are not needed to invoke 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?

For a mutation tool with no annotations, no output schema, and only 33% schema coverage, the description is incomplete: it says nothing about the result, permissions, or what happens on invalid input, and only partially addresses parameter meaning.

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 33%: value is well documented in the schema, but slug and source are undocumented in both schema and description. Worse, the description's 'numeric answer' undersells the schema's value semantics (string/boolean/null are stored but excluded from aggregates), adding confusion rather than compensating 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 verb and resource ('Submit a numeric answer to a poll'), so the basic action is identifiable. However, the word 'numeric' is inaccurate given the schema accepts string/boolean/null, and the sibling differentiation is a non-distinguishing claim ('Same as submit_answer') rather than a real contrast.

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

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

There is no when-to-use guidance or any condition distinguishing this from the many siblings (submit_answer, answer_ask, create_ask, etc.). Saying 'Same as submit_answer' asserts equivalence without helping an agent choose between them.

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

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

With no annotations, the description carries the full burden and does so richly: it discloses the return shape (url, mode, unlock_token), the test-mode card to pay with, that the token reads answers only after payment, the 409 awaiting_answers guard, that it does NOT POST to the asker's callback_url, and that pricing is USD with adaptive pricing off. These are exactly the side effects and payment semantics an agent needs.

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 correctly front-loaded in the first sentence, but the tail becomes fragmented and partly off-topic ('Poll unlock $1. Asker posts $1–$5. Reader unlock $1. Answers are free.') — pricing for the asker/answers does not help invoke this tool. The run-on sentences dilute an otherwise information-dense 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?

For a payment-flow tool with no annotations and no output schema, the description covers return values, error behavior, side effects, and payment mode thoroughly. The remaining gap is parameter documentation (especially payer_type), which is the one thing an agent still cannot resolve.

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

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

Schema coverage is 0% and neither parameter is explained. The description implies ask_id's role ('an ask you did not post') but never documents the payer_type enum (human/agent), leaving a required decision undocumented in both schema and description. It does not compensate for the coverage 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 ('Separate $1 reader checkout for an ask you did not post') and pins it to an endpoint, making clear it is the reader-side unlock rather than create_checkout or unlock_poll. An agent can distinguish it from all 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 clear context for use ('for an ask you did not post'), a follow-up step ('then get_ask with that token'), and a precondition (409 while awaiting_answers is true, so you don't pay for an empty thread). It stops short of explicitly contrasting with create_checkout or unlock_poll, so it is strong context rather than full when/when-not routing.

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses the return shape (url, mode, unlock_token), the payer_type default, fixed USD currency, disabled adaptive pricing, and the pricing model ($1 unlock, $1–$5 posts, free answers). It omits auth requirements, idempotency on repeat unlocks, and error behavior, keeping it short of 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?

The facts are present but fragmented and repetitive: '$1 poll unlock' in the opening is restated as 'Poll unlock $1' later, and the pricing sentences read as notes rather than a structured flow. It is not bloated, but it is not front-loaded cleanly either.

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

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

For a 2-param tool with no output schema, the description covers the return object, defaults, currency and pricing, which is most of what an agent needs. Missing auth/permission and repeat-unlock behavior are the notable gaps.

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

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

Schema description coverage is 0%, so the description must compensate. It documents payer_type's default ('Omitted payer_type is agent') and its enum semantics, but says nothing about the required slug parameter beyond what its name implies, leaving half the parameters unexplained.

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 ('Start a $1 poll unlock') and equates it to the sibling create_checkout, which helps an agent place it. It doesn't explicitly contrast with unlock_ask, the likely adjacent sibling, so sibling differentiation is incomplete.

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?

'Same as create_checkout' implies when this tool applies by analogy, but there is no explicit when-to-use/when-not guidance nor a direct comparison to unlock_ask. Usage is inferable rather than stated.

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