Problee

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

Annotations already declare read-only, idempotent, open-world and non-destructive behavior. The description adds substantial context beyond that: hypothetical external taker assumption, six BUY-side targets, strict one-IOC fill/spread limits, shared maker capacity, no residual price on exhaustion, partial results remaining incomplete, and no reservation or signing authority.

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, but the description then becomes dense and jargon-heavy, with phrases like 'Six independent BUY side × 100/500/1000-BPS targets consume prices strictly below initial selected ask + offset' that are difficult to parse. Most sentences carry relevant constraints, but readability suffers.

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 complex, specialized analysis tool with annotations and an output schema, the description covers many behavioral constraints: static selected-book scope, no dynamic repricing, incomplete partial results, and committed-ledger capacity corroboration. Some core terms remain opaque, but the overall behavioral contract is substantially documented.

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 50%, so the description must compensate for undocumented parameters. It largely repeats the schema's makerAddresses constraints (up to 64, no ownership inference) and does not explain scope, chainId, or marketAddress semantics 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 states a specific verb and resource: read-only static selected-book ask movement for a selected maker roster, with exact costs and one-IOC limits. It distinguishes the result from ordinary self-excluding sweep quotes, though it does not name a specific sibling tool such as get_orderbook or estimate_market_order.

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 the instruction to supply up to 64 maker addresses and by the contrast with ordinary self-excluding sweep quotes. However, there is no explicit 'use this when' or 'use X instead' guidance against the many orderbook and estimation siblings.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real value beyond them: the effect is off-chain DB membership ('No on-chain linkAddress transaction') and requires root-level authority. It does not explain what happens to consents that fail within a batch, which is the main remaining behavioral gap.

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

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

Four short sentences, front-loaded with the action and its destination, then authority requirement, then input provenance, then the off-chain clarification. No filler, though the 'up to 20 per call' detail partially duplicates the schema's maxItems constraint.

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?

An output schema exists, so return values need not be explained, and the description covers authority, batching, input source, and the absence of an on-chain transaction. The only thing an agent might still want is partial-failure semantics for a mixed batch.

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 explaining the provenance of the 'consents' array (pending list output or post-submit membership snapshot) and by stating the 20-item batch ceiling in operational terms. The idempotencyKey is left to the schema, which is acceptable given its inline 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 (bulk-approve) applied to a specific resource (staged link consents) with the resulting effect (protocol DB membership), plus the batch cap. It is instantly distinguishable from the producer siblings problee_list_pending_link_consents and problee_submit_link_consent.

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 preconditions (authenticated agent's bound operating wallet must be the verified root) and names exactly where the input consents come from — the pending list tool or the membership snapshot after submit_link_consent. It does not explicitly say when not to use it or what to do if only one consent exists, but the context is clear enough for correct selection.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds the useful output contract of one entry per input wallet with order preserved, but says nothing about partial failures, invalid addresses, or what "black-box" scoring means in practice. A 3 is appropriate given the lower bar set by rich 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?

Two short sentences with no filler; the capability and the cardinality limit are front-loaded and the return shape follows. Nothing is redundant.

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 an output schema present and four annotations, the description only needs to frame the batch contract, which it does. The remaining gap is error/partial-failure behavior for a batch of up to 100 addresses, which is a plausible thing an agent would want to know before calling.

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% on the single walletAddresses parameter, including the EVM address pattern and the 1–100 bounds, so the schema already does this work. The description's "up to 100 wallets" only restates maxItems without adding format or semantic detail.

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 pairs a specific verb ("Resolve") with a specific resource ("black-box public reputation (tiers, gates, track record)") and states the batch scope of up to 100 wallets in one call. That batch framing is what distinguishes it from the singular problee_get_counterparty_reputation, though the sibling is never named explicitly.

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

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

Usage is only implied: an agent can infer this is the bulk path when it has many addresses, but the description never says when to prefer this over problee_get_counterparty_reputation or other reputation siblings, nor states any exclusion. No prerequisites or rate considerations are mentioned.

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 and non-destructive, so the safety profile is covered. The description still earns credit for two non-obvious traits: the authenticated wallet is excluded server-side and cannot be supplied, and the call is all-or-nothing ('any item failure fails the whole call'). Those additions are genuinely useful but the disclosure stops there.

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 compact sentences with the resource and cardinality front-loaded and the failure semantics second. Nothing is padding, though 'ordered' is mildly ambiguous wording that could be tightened.

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

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

An output schema exists, so return values need no explanation, and the description covers scope, cardinality and failure mode. What remains missing is the routing guidance against the single-book siblings, which matters given how many orderbook-related tools exist.

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%, including descriptions of side, view, depth, chainId and marketAddress, so the schema carries parameter meaning. The description adds only the item-count bound and 'ordered', and it is unclear whether 'ordered' means preserved result ordering or a sequence of requests.

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 ('Get ... destination books') with batch scope and a distinguishing qualifier ('caller-executable'). It does not name the likely alternatives (problee_get_orderbook, problee_get_market_depth), so an agent must infer the batch-vs-single split rather than being told it.

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 1-to-100 range and plural 'books' imply this is the multi-market read path, but the description never says when to prefer it over the single-book siblings or lists any prerequisite or exclusion beyond the batch size.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, and the description adds real value on top by establishing that the rules are static and that the tool performs only rules work. It does not disclose what happens when some of the requested addresses are unknown or have no rules — the main behavioral unknown for a batch read — so it falls 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?

Two sentences, zero filler: capability and contents first, then the sibling comparison and exclusions. The front-loading is exactly right for a decision an agent must make before calling.

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

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

An output schema exists and annotations cover the safety profile, so the description does not need to explain returns. What is left out is batch failure semantics (partial results vs. error on unknown markets), which would matter for an agent assembling a 200-address call. Otherwise the definition is sufficient 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?

With schema description coverage at 50%, both parameters carry terse schema docs (chain ID with a Base 8453 hint, and address format). The description reinforces the 200-market cap but adds no meaning about chainId selection or address list semantics beyond what the schema already states. Baseline 3 is appropriate; the description neither compensates for nor worsens 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 names a specific verb and resource ("Get static per-market orderbook trading rules") and enumerates the payload contents (price grid, size floors, fees, TIF, STP) along with the batch scope of up to 200 markets. It also explicitly contrasts itself with problee_get_market, so an agent can distinguish it from siblings 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?

It gives explicit routing guidance: "Use this instead of polling problee_get_market per market." It also states the negative space — no volume, reputation, resolution surfaces, or prices — which tells the agent when this call is not sufficient and that other tools are needed for those surfaces.

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 (which only say it is a non-destructive write in an open world), the description discloses rate-limiter accounting (one write credit regardless of batch size), partial-success semantics, the per-result `error` field, CLORDID_CONFLICT on divergent economics, and the wallet-proof requirement. These are exactly the operational facts an agent needs before firing a 50-order batch.

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

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

Four tight sentences, front-loaded with the batch cap and rate-credit fact, then prerequisite, then failure model. Nothing is padding; every clause carries operative information.

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

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

With an output schema present it correctly omits return-value descriptions while flagging the `error` field that matters, and the proof/key prerequisites are covered by the schema. The only shortfall is that it does not point to the sibling tool that produces pre-signed orders, which is the natural upstream step.

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 nonetheless adds meaning by tying orderSignature/nonce presence to batch mode and mapping clOrdId behavior to the CLORDID_CONFLICT result. It does not go further into per-order field semantics, which the schema already handles in depth.

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

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

The description opens with a specific verb, resource and batch scope ('Place up to 50 pre-signed limit orders in one call'), and the 'pre-signed / no signing-payload return path in batch mode' clause implicitly separates it from the singular place_limit_order and from prepare-order siblings. An agent can identify the tool's role 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?

It states the key precondition (orders must already be signed with nonce) and implies that preparation happens elsewhere, since batch mode returns no signing payload. It does not explicitly name the alternative tools (batch_prepare_orders, place_limit_order) or state when a single order or the prepare path should be chosen instead.

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 mark this non-destructive and non-read-only, and the description adds the crucial behavioral fact that nothing enters matching — a real disclosure beyond structured fields. Gaps remain: it doesn't note that the wallet proof nonce is single-use/consumed or that idempotentHint is false despite a required idempotencyKey, both of which affect retry behavior.

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

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

A single tight sentence with the cardinality and the non-mutating guarantee front-loaded, and nothing wasted. It is, however, terse to the point of leaving the follow-up action unstated, 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?

The rich schema and an output schema relieve the description of documenting fields and return values, and annotations cover safety. But for an auth-gated preparation step feeding a separate placement tool, the description omits the end-to-end flow and the interaction with problee_batch_place_orders, leaving a meaningful 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 coverage is 67% and the per-parameter descriptions are unusually rich (price grid, minRestingShares, basis-point conversion, orderSignature semantics). The description contributes only the 1–50 cardinality, which the schema already enforces via minItems/maxItems, so it adds little meaning beyond the schema.

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

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

States a specific verb and resource ('Prepare ... unsigned EIP-712 orders') with an explicit batch bound (1–50) and a clear scope limit ('creates signing payloads only and accepts nothing into matching'). That scope clause implicitly distinguishes it from problee_batch_place_orders, but the sibling is never named, so the agent must infer the pairing.

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 phrase 'creates signing payloads only' suggests a sign-then-submit workflow, but the description never says what to do with the returned payloads, nor points to problee_batch_place_orders as the follow-up step. No prerequisites (wallet proof, nonce, idempotency key) or when-not-to-use guidance appear.

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 (destructiveHint=true, readOnlyHint=false), the description discloses what actually gets destroyed (terminal hosted cancellation of named predecessors, post-only successors) and the partial-failure contract (a failed market never voids its neighbours). It stops short of describing the signing/proof flow or what 'one write credit' means for retries.

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

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

Three dense sentences, front-loaded with the scope and atomicity guarantee; every clause carries operational meaning and nothing is repeated from the schema or annotations.

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

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

For a destructive batch write with an output schema, the description covers scope, atomicity, failure isolation, and the size limit. The remaining gap is the authorization path — walletAddress/walletSignature/proofNonce/signatureTimestamp are required but the description gives no hint about obtaining the nonce or signing sequence, which would matter before a first 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?

With only 50% schema description coverage, the description contributes one genuinely new constraint — the aggregate 50-order cap across all items, which is not expressible in the schema's per-item maxItems of 50. It does not explain idempotencyKey semantics (which the schema leaves undocumented) or the suspendOrderHashes field that supplies the 'named predecessors'.

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 ('Replace hosted quote sets'), the batch scope ('across up to 10 markets in one request'), and the cost model ('one write credit'), which cleanly separates it from the single-market sibling problee_replace_quote_set.

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

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

The batch scope implies when to reach for this tool (multiple markets in one call), but there is no explicit when-to-use/when-not guidance and no named alternative such as problee_replace_quote_set for a single market or problee_batch_place_orders for additive placement.

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 (which only say it is a non-read-only, open-world, non-destructive write), the description discloses the crucial behavioral facts: the first call is free, charging only occurs on the second call with `payment`, and idempotency context matters for retries. It also discloses the non-obvious delivery semantics — PM lands on the wallet bound to this key, not the paying address — and the value constraint that PM is non-redeemable and has no cash value.

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 two-step flow is front-loaded and the value caveats come at the end, which is the right order. It wastes some space repeating "nothing is charged" twice in one sentence and packs several independent facts into a single em-dash chain, but no sentence is expendable.

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?

An output schema exists, so return-shape explanation is rightly omitted, and the description covers the charge model, delivery destination, and redemption limits that an agent needs before spending. The one gap is that `usd` must match a "listed purchase bundle" without saying where those bundles are listed or what the allowed values are, which matters because there are no enums on the parameter.

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 all three parameters are already documented in the schema, including the `payment`-omitted first call. The description reinforces the token/quote semantics of `usd` (registry quote, same rate as the card rail) but adds no syntax, format, or bundle-list detail beyond what the schema states. 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?

"Buy PM (Kellian play money) with USDC on Base" states a specific verb, resource, and settlement rail, which no sibling tool covers (the nearest, problee_plan_pm_order, is planning rather than purchase). An agent can distinguish this from balance, plan, and trade tools without opening any schema.

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

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

The description gives explicit procedural guidance: call once with no `payment` to receive the x402 requirements, then sign and call again with the base64 payload. That removes the main sequencing ambiguity for a two-phase tool. It stops short of naming alternatives (e.g., problee_plan_pm_order, or the card rail it references) as when-to-use-this-vs-that 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?

Goes well past the annotations: it declares the effect terminal, states there is nothing to broadcast and no gas owed, and explains the non-obvious exception that orders with committed taker reservations are suspended and settle later. It also flags pagination and the wallet-proof requirement, which the destructiveHint alone would not convey.

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

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

Three tight sentences, front-loaded with the terminal/no-gas guarantee that matters most. Every sentence carries information, though "on the page" is a small source of ambiguity that could be trimmed.

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

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

Covers scope, side effects, the taker-reservation edge case, pagination, and the auth proof requirement for a 9-parameter destructive tool, and an output schema exists so return values need no explanation. It could still say whether a separate confirm step is ever required.

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 78%, so the schema already documents most parameters including the market filter and proof nonce. The description adds only the mapping of "optionally scoped to a market" and "paged" to the filter and cursor arguments, without new format or constraint detail.

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 ("cancel every open order") plus a concrete layer ("at the hosted layer"), which separates it from on-chain cancellation siblings. The phrase "on the page" muddies scope by suggesting page-local cancellation, and no sibling such as problee_cancel_order or problee_confirm_order_cancel is named.

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 through "optional market scoping" and the terminal/hosted nature, which hints no confirmation round-trip is needed. It never says when to pick this over problee_cancel_order, problee_cancel_orders, or problee_confirm_order_cancel, so an agent must infer the 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?

Beyond the annotations (destructiveHint=true, idempotentHint=false, openWorldHint=true), the description adds genuinely non-obvious behavior: cancellation is hosted and terminal, requires no on-chain broadcast or gas, and a committed taker reservation suspends termination until the fill settles or releases. It does not cover auth/proof prerequisites or idempotent-retry semantics, but the preconditions and the suspension state are real value the annotations cannot convey.

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

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

Three sentences, front-loaded with the action and identifier choice, then the terminal/hosted semantics, then the one edge case (taker reservation suspension). No sentence repeats the title or the schema, and nothing is padding.

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

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

With an output schema present, return values need not be described, and the 100%-covered 7-parameter schema carries the auth and idempotency detail. The description covers the mutation's consequence and the suspended-order state, which is the main thing an agent could get wrong; only explicit sibling routing and error/retry behavior are absent.

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

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

Schema description coverage is 100%, so every parameter including clOrdId, orderHash, and the wallet-proof fields is already documented in the schema. The description only restates that the target may be given as a hash or client order id and adds no format, precedence, or conflict guidance beyond that baseline.

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

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

The first sentence gives a specific verb and resource ('Cancel an order') and names the two identifier modes (order hash or client order id), so the agent knows exactly what the tool acts on. It does not, however, distinguish itself from the confusable siblings problee_cancel_orders, problee_cancel_all_orders, or problee_confirm_order_cancel, so the agent must infer whether this is the singular, authoritative path.

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: 'authoritatively' plus 'Provide this OR orderHash' signals a targeted single-order cancel as opposed to a bulk one, and 'terminal' implies no follow-up confirmation step is needed (relevant against problee_confirm_order_cancel). No sentence explicitly states when to choose this over those siblings or when not to use 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?

Adds real behavior beyond the annotations: per-hash independent reporting, the rule that unknown/already-terminal/not-yours does not abort the rest, and that the operation is hosted and terminal with no broadcast or gas. It does not address how the confirm_order_cancel sibling relates to this call, or the tension between the idempotencyKey parameter and idempotentHint=false.

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 the cap, then the positioning, then the failure semantics, then the no-gas note – a sensible order with no sentence that carries no information. The re-quoting-ladder illustration is slightly florid, but it is the sentence that justifies the tool's existence.

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

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

For a destructive batch mutation with an output schema and full annotation coverage, the description supplies everything needed to call it correctly: scope, sibling routing, partial-failure contract, and the absence of on-chain steps. The only gap is the relationship to problee_confirm_order_cancel, which the description never mentions.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including the 50 cap, duplicate collapsing, nonce, signature challenge and idempotency key. The description's only parameter claim ('up to 50') repeats what maxItems already states, so baseline 3 applies.

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

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

States a specific verb and resource with a hard scope bound ('Cancel up to 50 named orders in one call') and immediately positions itself between 'cancelling one hash' and 'cancelling everything'. An agent can distinguish it from problee_cancel_order and problee_cancel_all_orders 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?

The alternatives are named explicitly and the selecting condition is given: when you need more than one hash but not a full book teardown (the re-quoting-a-ladder scenario). The only thing left implicit is that a single hash should go to the single-order tool, which the positioning makes obvious.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the meaningful scoping detail that markets live in a per-agent namespace, which explains why a negative result is not global; however, that nuance largely restates the title's 'this agent' phrasing and adds nothing about freshness, caching, or query cost.

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 sentences, front-loaded with the operation and followed by the namespace qualifier. No filler, no restated boilerplate, and the most important constraint arrives before any caveat.

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 parameter, an exhaustive annotation set, and an output schema covering the return value, the description only needs to establish intent and scope — both of which it does. The remaining gap is workflow guidance (what to do on true vs false), which is arguably adjacent to this tool's scope.

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% — the input parameter is an untyped string with only length bounds — so the description carries the semantic load. It explains that externalId is the identifier the agent itself supplied when deploying, which is real meaning beyond the schema, though it does not state the format, whether case sensitivity applies, or how a missing/mismatched id is treated.

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 check (does a market already exist) keyed on a named identifier (externalId), which is a distinct verb+resource combination an agent can recognize. It does not name a sibling tool to contrast with, but none of the siblings overlap this exact idempotency check, so differentiation is implicit rather than spelled out.

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 implies the use case — verifying prior deployment before re-deploying with a given externalId — but never states it explicitly, nor does it say when not to use it or what to do with the result (deploy vs skip). The agent must infer the workflow from the title's 'Idempotency check' framing.

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

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

The description adds real behavior beyond the annotations: a precise state machine (OPEN|PARTIALLY_FILLED stays MINED/PENDING_FINALITY until exact canonical evidence exists; CANCELLED|FINALIZED only when the cancellation is already canonical). The proof requirement plus the schema's single-use proofNonce explains the non-obvious destructiveHint=true / idempotentHint=false pair, so there is no contradiction, though the description itself never says the nonce is consumed.

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

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

Three sentences, front-loaded with the core action and the return states, with no filler. The phrase 'exact canonical tx/log evidence' is repeated in near-duplicate form across the second and third sentences, which is the only mild redundancy.

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

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

An output schema exists, yet the description still summarizes the meaningful outcome states, and it covers the proof prerequisite and the mined-tx constraint. For a seven-parameter mutation-adjacent tool this is close to complete, missing only an explicit note on what happens if the tx is not yet mined.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters, which sets the baseline at 3. The description contributes one extra fact only: that walletSignature/walletAddress must be the same maker proof used at preparation time, a cross-call linkage the schema does not state.

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

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

States a specific verb and resource: 'Verify a mined OrderCancelledEvent', and outlines the exact outcome states it reports. It implicitly separates itself from the broadcast-cancel siblings (problee_cancel_order, problee_cancel_orders) by requiring an already-mined tx, but never names those siblings to make the boundary explicit.

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 'mined' qualifier and 'used to prepare cancellation' tell an agent this is a follow-up step to a prepared/broadcast cancellation. There is no explicit when-not-to-use guidance and no pointer to alternatives such as problee_get_transaction_status for general tx finality or problee_cancel_order for initiating a cancellation.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context beyond them: forecasts are scored once at the minute of submission, up to 3 per question per day, none counted outside 5%-95% price, lower score is better, and others' numbers stay hidden until the lock. It stops short of disclosing pagination or how the 'week' window affects the boards.

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 one dense paragraph that opens with tournament rules instead of the tool's action, so the useful part (what is returned, key requirement) arrives last. The scoring and prize detail is relevant but could be trimmed or moved behind the front-loaded purpose sentence.

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?

An output schema exists, so return values need not be spelled out here, and the prize/scoring rules are a genuine plus. But for a two-parameter tool with zero schema coverage, the total absence of parameter meaning leaves the definition incomplete 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 0% and the description never mentions either parameter. 'all' and 'week' (1-20) go entirely unexplained, so the agent must guess whether 'all' means all questions or all boards, and what a week number selects. This is a clear gap where the description should have compensated.

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 final sentence states the specific output: featured questions, category boards, and the caller's entry. The bulk of the description explains the contest rather than the tool, but an agent can still tell this is a read of contest state. It does not explicitly distinguish itself from the close siblings problee_my_contest and problee_get_scoring_record, which keeps it from 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?

It points to problee_publish_forecast as the way to submit forecasts, which is a useful routing cue, and it implies a key is needed to see 'your entry'. However, it never says when to use this tool versus problee_my_contest, problee_join_contest, or the scoring-record tools, leaving the main selection question unanswered.

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=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds non-obvious behavior: alerts fan out to the site plus the named channels, re-watching extends rather than duplicates, and the feature is plan-gated ("Part of Plus"). It stops short of stating auth requirements or any limits on how many watches an account may hold.

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

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

Front-loaded with the core action, then the worked trigger example, then the extension rule and delivery note — every sentence carries information. The embedded quoting of a nested JSON literal is slightly hard to parse, but nothing is padding.

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

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

For a 5-parameter tool with a deeply nested target union, an output schema, and full annotations, the description supplies what structured fields cannot: delivery targets, upsert semantics, plan gating, and a trigger example. The unmentioned portfolio target kind and the absent frequency discussion are the only real omissions.

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 already 80%, so the baseline is 3. The description earns above baseline by giving a concrete triggers payload ("A Tier 1 trader buys" is triggers [{kind:"smart_money", maxTier:1, minUsd:1000, side:"buy"}]) that makes the polymorphic trigger union concrete. It says nothing about the frequency parameter, which the schema covers on its own.

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

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

The description opens with a specific verb ("Watch") and enumerates the resources: a Polymarket question, an option, a smart money trader, a forecaster, a category. It also states the effect (Kellian alerts the account that owns this key when it moves), which distinguishes it cleanly from siblings like problee_list_watches and problee_delete_watch. Only gap: the schema's "portfolio" target kind is not mentioned.

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 one genuinely useful usage rule — re-watching the same target extends the existing watch rather than creating a duplicate — plus the "Part of Plus" entitlement note. But it never names alternatives or when-not to use it (e.g., how to view watches, how to remove one), leaving routing 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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds genuinely new context about the authority model (ownership-governed by market creator wallet, no scope needed) and the eligibility restriction on which updates can be removed. It says nothing about irreversibility, required wallet proof/nonce, or idempotency despite the annotations declaring non-idempotency alongside a retry key in the schema.

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

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

Two sentences, zero filler, with the action and its ownership constraint front-loaded before the eligibility rule. Every clause carries information.

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

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

For an 8-parameter, destructive, proof-signed mutation with an output schema, the description covers the crucial authorization and eligibility model, which is the main non-obvious aspect. It leaves signing/nonce and retry behavior entirely to the schema, which is acceptable at 88% coverage but leaves a small gap for such a high-stakes operation.

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 88%, so the schema already documents id, chainId, walletAddress, proofNonce, walletSignature, signatureTimestamp, and idempotencyKey. The description only adds the implicit mapping of 'market creator wallet' to the walletAddress parameter; it does not clarify the auth-proof parameters or the retry semantics. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb ('Delete'), a specific resource ('persistent canvas updates'), and a scope limit ('your own ... from a market you created'). The verb alone separates it from the sibling post/list canvas tools, so the agent can pick it without opening a schema.

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

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

Gives clear preconditions: the caller must be the market creator wallet, and only updates posted by that same wallet are eligible. It does not name an alternative path (e.g., listing updates first to obtain the id) or state explicitly when not to use it, so it falls short of full when/when-not/alternatives coverage.

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

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

The annotations already declare this is a non-read-only, non-destructive operation. The description adds useful behavioral context by clarifying that existing alerts remain in the log after the watch is stopped, though the lapsed-member sentence is unclear and retry/idempotency behavior is left to the schema.

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

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

The description is short and front-loads the action and resource. However, the final fragment, "A lapsed member may too," is ambiguous and weakens clarity without clearly earning its place.

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

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

This is a low-complexity, two-parameter tool with full schema coverage, annotations, and an output schema. The description covers purpose and the key retention behavior, though the eligibility note is vague and there are no explicit exclusions.

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

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

Schema description coverage is 100%, so both parameters are already documented. The description only reinforces that the ID comes from problee_list_watches and adds no additional meaning for the idempotencyKey beyond what the schema 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 uses a specific verb, "Stop," and a specific resource, "watch," and states it acts by ID. Referencing problee_list_watches for the ID also distinguishes it from the sibling list and create watch tools.

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

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

It clearly tells the agent to obtain the watch ID from problee_list_watches, which implies the correct usage context. It does not explicitly state when not to use it or name alternatives beyond the ID source, and the final sentence about a lapsed member is ambiguous.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine behavioral content beyond that: that reconnect/replay semantics exist, that execution.report is a wallet-scoped auto-delivered channel, and that webhooks are the async fallback path. It does not contradict the annotations in any way.

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

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

A single front-loaded sentence leads with the primary subject (the WebSocket transport) before the secondary topics, and no clause is filler. The dense parenthetical stacking ('URL, auth schemes, message shapes, reconnect/replay protocol') makes it slightly harder to scan than a short bulleted opener, but it stays within one sentence.

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 an output schema present, the description need not explain return values, and its enumeration of covered topics is sufficient to decide whether to call it. The one remaining gap is that it does not clarify how this tool divides work with the closely named problee_discover_webhooks sibling, which would matter for an agent choosing between the two.

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; baseline 4 applies. No parameter claims are made that could mislead.

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 specific deliverable (the Agent WebSocket transport spec) and enumerates its contents: URL, auth schemes, message shapes, reconnect/replay protocol, plus the WS↔webhook taxonomy bridge and wallet-scoped execution.report channels. That is far more concrete than a bare 'describe' verb. It stops short of distinguishing itself from sibling problee_discover_webhooks, whose subject matter it partly overlaps.

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 rather than stated: an agent can infer it should call this to learn the streaming transport before integrating, and the phrase 'webhooks as the async fallback' hints at the relationship to the webhook path. There is no explicit when-to-use / when-not-to-use rule and no named alternative (problee_discover_webhooks, problee_list_capabilities) that an agent should pick instead.

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/openWorld, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: this is a descriptive documentation surface, not an execution path, and the authoritative execution lane lives elsewhere. It does not discuss caching, freshness, or rate limits, but the core behavioral framing is present.

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

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

Two sentences, with the purpose front-loaded and the caveat about execution authority placed at the end where it belongs. The parenthetical enumerations inside the first sentence make it dense, but every clause maps to a distinct lane rather than padding.

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

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

With zero parameters and an output schema present, the description's job is scoping only, and it delivers that by naming the lanes covered. An agent knows what it will learn from a call and where that knowledge does not extend (execution). No material gap for a parameterless discovery 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, so per the baseline there is nothing for the description to disambiguate. The listing of lanes is informational rather than parameter-related, which is appropriate here.

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

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

States a specific verb and resource ('Describe the canonical market-data lanes') and enumerates exactly what it covers: WebSocket subscribe/channel/message shapes, REST snapshot/quote/orderbook, consumer SSE, and the agent control-plane WebSocket. That enumeration distinguishes it from sibling discovery tools like problee_discover_events or problee_discover_webhooks, though it doesn't name them 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?

The closing sentence tells the agent that quote/order-book tool calls remain the execution-authoritative path and this only describes realtime/display lanes, which implies when to reach for it. It stops short of stating when to use this versus the other problee_discover_* tools, so the routing decision is only partially supported.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered structurally. The description adds that the listing includes data schemas and examples, which is useful content context beyond the annotations, but says nothing about rate limits, freshness, or whether the catalog is static.

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

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

Two tight sentences with no filler: the capability statement is front-loaded and the routing note follows. Every clause carries information an agent can act on.

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 an output schema defined, return values need not be described, and the annotations carry the safety profile, so the remaining burden on the description is light. It covers what is listed and where it fits in the publishing workflow; only a clearer tie-in to when this discovery step is needed is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter-level detail is omitted because no parameters exist.

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

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

The description gives a specific verb and resource: "List the built-in market surface renderer types," plus the payload detail ("with data schemas and examples"). The resource 'renderer types' is distinct from the other problee_discover_* siblings, though the description never explicitly contrasts itself with 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 routes agents by skill level: beginners should call problee_publish_market_surface, while problee_push_content is the advanced raw envelope path. That is clear contextual routing, but it frames the downstream publishing choice rather than stating when to call this catalog tool (e.g., before publishing) or when to skip 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?

Annotations already cover read-only, idempotent, open-world, and non-destructive safety. The description adds a key data-model convention: there is no closed enum and agents invent their own type values, which is not captured in structured fields.

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

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

Two sentences, front-loaded with the purpose and a critical convention. No filler or repetition; 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?

Output schema exists, so return values need not be explained, and annotations cover safety. The description is adequate for a zero-param discovery tool, though it could clarify when to invoke it relative to other discover_* tools.

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

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

Zero parameters, and schema coverage is trivially 100%. Per calibration, 0 params yields a baseline of 4. The description adds no parameter semantics because none exist.

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

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

States a specific verb ('Describe') and resource ('resolutionSource envelope shape and conventions agents use'). The resource is distinct from sibling discover tools like events, market_data, renderers, and webhooks, so an agent can tell it apart without opening schemas.

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

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

No explicit when-to-use or when-not-to-use guidance. The description states what the tool describes but does not name alternatives or conditions that select it over sibling discovery tools like problee_discover_events.

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 destructiveHint=false, so the safety profile is covered. The description adds content-level transparency (it tells you the doc's depth: algorithm, envelope shape, replay tolerance). It does not disclose anything further behavioral — versioning, whether it reflects live server config, or freshness — so a 3 is appropriate.

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

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

A single front-loaded sentence with a tight parenthetical enumeration; every clause earns its place and nothing is redundant or 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?

For a zero-parameter discovery/doc tool with an output schema present, the description need not explain return values, and it adequately conveys what the call yields. Minor gap: it doesn't note whether the returned scheme description is versioned or static.

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 (empty object schema, 100% coverage), so per the rubric the baseline is 4. There are simply no parameters for the description to explain.

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

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

Specific verb ("Describe") plus a precisely named resource ("the Standard Webhooks signing scheme") and an enumeration of exactly what the doc covers: headers, HMAC-SHA256, envelope shape, replay tolerance, and the url_verification handshake. An agent knows this returns webhook-signature documentation, not event listings. It does not explicitly distinguish itself from the sibling problee_list_webhook_event_types, 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?

"So a receiver can verify deliveries without reading source" clearly states the intended context: use this when implementing or validating a webhook receiver. That is a concrete usage cue. However, no when-not condition or explicit alternative (e.g., list_webhook_event_types for event payloads) is given.

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 read-only annotations, the description discloses that no maker liquidity is reserved, no gas is spent, no wallet proof is required, and self-trade exclusion depends on whether a wallet is bound. It also explains the minimum-size failure behavior and the IOC relationship to live placement.

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 and uses clear section labels for sizing, minimums, and execution behavior. It is longer than necessary because the minimum/deprecated-field history and amount-mode semantics are repeated across the description and schema.

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

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

Given a high-complexity pricing tool, complete schema descriptions, rich annotations, and an output schema, the description covers the remaining agent-relevant behavior: liquidity/gas cost, wallet-dependent self-trade behavior, minimum-size outcomes, and placement handoff. Nothing critical for correct invocation appears missing.

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

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

The schema already documents amount, maxSpend, amountMode, limitPrice, and minimums at 100% coverage, so the description is largely reinforcing schema semantics. It still adds useful cross-field interpretation, notably the Polymarket meaning mismatch and the instruction to read the echoed amountMode rather than assume it.

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 gives a specific verb and resource — price an order before placing it — and enumerates the outputs: estimated shares/amount, average price, worst-leg price, and partial-fill flag. It also distinguishes this preview from the live placement path by naming problee_place_limit_order.

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

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

It explicitly says to call this before placing a market order and as often as sizing requires, and it names the alternative execution path (problee_place_limit_order with IOC). It also states the no-wallet self-trade caveat that changes how the estimate should be interpreted.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds real context beyond them: the protocol fronts gas, the agent holds no ETH and manages no nonce, and a re-posted signed intent cannot execute twice because the digest is single-use. It adds no failure-mode detail (expired deadline, revert handling), which is what keeps it below a 5. The replay-safety sentence is narrower than the idempotentHint=false annotation and is consistent with it, not contradictory.

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

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

Four short sentences, front-loaded with the action and the key differentiator (gasless, no nonce), then the call sequence, then the safety guarantee. No filler and no repetition of the title.

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

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

An output schema exists, so return values need not be described, and the description covers the cross-tool workflow and the safety profile an agent needs before a mutation. It leaves chainId unexplained and gives no guidance on failure/retry outcomes, which is a modest gap for a write operation.

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 75% and the description mostly restates what the schema says, pointing at intent as the unchanged signPayload typed-data message. chainId and the retry semantics of idempotencyKey are left entirely to the schema, so the description adds little meaning on top of it.

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 (execute a signed trade intent) and immediately names the mechanism (protocol submits on-chain, pays gas), which cleanly separates it from problee_prepare_trade and from order-placement siblings like problee_place_limit_order.

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

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

Gives an explicit prerequisite and ordering: sign the signPayload from problee_prepare_trade first, then call this. It does not state when to prefer alternatives (e.g. problee_simulate_trade for dry runs or the batch preparation path), so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real value beyond that: no onchain transaction, protocol DB membership only, and an authorization prerequisite on the caller's wallet. The 3-minute TTL is only in the title, not the description body, and there is no note on rate limits or whether a new code supersedes an older one — small but real gaps for a mutating 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?

Four short sentences, each carrying distinct information: what is produced, the auth gate, the consumer workflow, and the side-effect scope. Front-loaded with the action and the artifact, with the alternate path correctly placed last.

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?

An output schema exists, so return values need no explanation. For a mutation tool with an authorization gate and a multi-step downstream flow, the description covers precondition, effect scope, and orchestration — everything an agent needs before calling 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?

There is one parameter at 100% schema description coverage, so the schema already explains idempotencyKey's retry semantics and length bounds. The description adds nothing about it, which is acceptable at this coverage level but leaves the baseline score.

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 with concrete attributes: 'Generate an 8-character multi-use link code for bulk agent/wallet linking.' It is instantly distinguishable from sibling link tools (problee_submit_link_consent, problee_approve_link_consents, problee_unlink_identity_wallets) because it names the code-generation step of that flow.

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

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

Gives an explicit precondition ('bound operating wallet must be the verified root address'), a downstream workflow (share → each agent submits consent via problee_submit_link_consent → bulk-approve via problee_approve_link_consents), and a named alternative channel (the kellian.app identity linking page). An agent knows both when to call this and what to do next.

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 this a readOnly, idempotent, non-destructive, open-world operation, so the safety profile is fully covered. The description adds the scope of state it surfaces (membership, migration, authorization, next steps), but does not mention any access requirements, freshness/caching behavior, or what an unverified/new agent sees. Since an output schema exists, the field enumeration is useful orientation rather than essential disclosure.

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

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

A single dense sentence with the core purpose front-loaded and the sibling comparison appended, so nothing is buried. The list of returned facets is slightly enumerative and reads close to a restatement of the output schema, but it is compact enough not to be 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?

For a zero-parameter, read-only, self-scoped tool with a full output schema and rich annotations, the description covers purpose, scope, and sibling routing adequately. The only gap is the absence of any hint about what state a brand-new or unlinked agent would report, which would help first-call interpretation.

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 is the baseline-4 case: there is nothing for the description to disambiguate. The description does implicitly confirm self-scoping ('this agent's identity'), so an agent understands no identifier argument is required.

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

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

The description opens with a specific verb+resource ('Read this agent's identity state') and then enumerates the exact facets returned: stored membership, verification/migration state, creation authorization, next steps, and identity links. It also explicitly positions the tool against the sibling problee_get_me, so an agent can distinguish the two 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?

It gives clear situational context by saying the tool is 'richer than problee_get_me for identity linking', which tells an agent to prefer it when link/membership detail is needed. It stops short of explicit when-not guidance or naming what get_me should be used for instead, leaving some 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 openWorld, so the safety profile is covered. The description adds the useful 'black-box' framing, implying the response is an aggregated verdict rather than raw underlying data, but it does not say what happens for an unknown or unregistered agent id, which is the main failure mode for an openWorld 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?

A single front-loaded sentence with the resource and scope before the mechanism, and no filler. 'Black-box' is slightly jargon-laden but carries real meaning about the return shape, so almost 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?

For a one-parameter read with an output schema and full annotation coverage, the description supplies enough: what it returns, whose reputation it is, and that it is public. The remaining gap is error behavior for unknown agent ids, which the output schema cannot express.

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?

Only one parameter and the schema already documents it at 100% coverage ('Registered agent id.'). The description restates that the lookup is keyed by agent id without adding format, source, or lookup semantics, so the baseline 3 applies.

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

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

States a specific verb (Read) and resource (public reputation) and enumerates the payload categories (tiers, gates, track record, evidence) scoped to a registered agent id. It implicitly separates itself from self-scoped siblings like problee_get_my_reputation via 'public' and 'by its agent id', but never names the sibling it differs from, so the distinction is inferential rather than stated.

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: 'public' and 'registered agent' hint that this is for looking up another agent rather than yourself, but there is no explicit when-to-use, no when-not-to-use, and no named alternative among the several reputation tools (get_my_reputation, get_counterparty_reputation, get_subject_reputation, get_trader_profile).

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, openWorld, non-destructive), and the description adds real behavioral depth beyond them: balances come from the lane the collateral settles on (committed ledger balance batched to Base vs onchain ERC-20 balanceOf), and values are raw integer strings in native decimals requiring division by 10^decimals.

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 tight sentences, front-loaded with purpose then mechanics. The lane/decimals explanation is dense but each clause earns its place; no filler or repetition of the title.

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

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

With an output schema present and annotations covering the safety profile, the description need only supply what structured fields omit, and it does: balance-source semantics, the default/all scope, and the decimals conversion caveat. Nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description nonetheless adds meaning the schema lacks, clarifying that a committed collateral is a venue-held ledger balance and an onchain one is an ERC-20 balanceOf, plus the decimal-string formatting of returned amounts.

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 ('Get collateral balances for a wallet') and immediately scopes it (PM by default, include="all" for every supported collateral). Distinguishable from the nearby list_collateral, which enumerates available collaterals rather than a wallet's balances.

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?

Explains the include default-vs-all condition and that chainId is optional only when a single chain is active, giving clear context for invocation. It stops short of naming an alternative sibling (e.g. get_positions) or stating when-not to use this tool, so it is clear but not fully 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond that: it does not say what 'claim status' contains (eligibility, claimed amount, claimant address), whether it requires the market to be resolved, or how it behaves for unresolved markets. With annotations carrying the safety burden, the description still leaves the substantive behavior unexplained.

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 single sentence is front-loaded and wastes no words, but it is undersized for the job rather than efficiently concise. Nothing is superfluous; there is simply almost nothing there.

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?

An output schema exists, so return values needn't be described, and only two parameters are involved. Nevertheless, given the dense cluster of claim- and resolution-related siblings, the definition omits the one piece of information an agent most needs: how this differs from get_resolution_status, list_claims, and simulate_claims.

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

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

Schema description coverage is 100%, with both chainId and marketAddress documented in-schema including format constraints and the default chain (Base 8453). The description adds no additional meaning about these parameters, so the baseline 3 applies rather than a higher score.

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?

Tautological: description restates name/title.

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, no statement of prerequisites (e.g. the market must already be resolved), and no pointer to any alternative. The agent is left to infer usage purely from the name and the single required marketAddress parameter.

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

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

Goes well past the annotations (readOnly/idempotent/non-destructive) by disclosing the things an agent cannot otherwise know: unauthenticated or free accounts get a degraded Free preview (5 markets, average only, 1 headline), and a meta block reports what was withheld. It also quantifies the compact view as 'a fraction of the tokens', which directly informs batching decisions.

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 prose is dense and front-loaded: the record shape comes first, filters second, tier degradation third, compact mode last. It earns its length given the aggregate payload, though the single run-on sentence with stacked parentheses is hard to parse and view=compact is effectively explained twice.

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 a full output schema and rich annotations already in structured form, the description still covers the parts an agent needs: what each record contains, how filtering and paging work, tier-based truncation, and the compact alternative. Nothing material for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, and the description largely restates the schema's filter modes and compact-view contents rather than adding format or precedence rules (e.g., how ids interacts with segment/category). Meaning beyond the schema is minimal.

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?

Opening clause names a specific verb and resource and scope: 'Every market's research in one call, one compact record per market', then enumerates the record's contents. It is clearly the bulk/sweep counterpart to the single-market siblings (problee_get_market, problee_get_market_research), but it never names the alternative, so the differentiation is inferable rather than explicit.

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 implies filtering modes ('Filter by segment, category or ids, or all; page with cursor') and offers a token-saving hint for view=compact, which helps an agent pick a mode. However, it never says when to reach for this tool instead of problee_get_market_research, problee_list_markets or problee_get_context_changes, and gives no exclusion or prerequisite guidance beyond the tier note.

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

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

Annotations already cover read-only, idempotent and open-world semantics, but the description adds genuinely non-obvious behavior: 'Each change comes once, in the first window after Kellian recorded it' (no duplicates across polling windows) and the tier gating for top-trader moves. It does not mention rate limits or what an empty result means, but the delta/continuation model is clearly disclosed.

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 tight sentences, front-loaded with the core delta semantics and the continuation rule before the compact-view and disclaimer details. Minor waste: the 'Plus and API Pro' entitlement is signaled twice, the compact-view details largely repeat the view parameter's schema description, and the closing 'Research, not financial advice' is boilerplate.

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 an output schema available, the description needn't describe return values, and it still covers the areas that matter most: what changes appear, ordering, once-only delivery, continuation via since=until, entitlement tiers, and the compact view. The only unaddressed parameter is cursor, which is a small omission given an otherwise complete picture for a six-parameter feed tool.

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

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

Schema description coverage is only 50%, and the description compensates meaningfully: it maps the six change categories to the types enum, spells out what view=compact returns, and defines since as 'the answer's until' — a relationship the schema's own note ('Your last call's until') does not fully operationalize. However, cursor and ids are never mentioned anywhere, which leaves a real gap at this coverage level.

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 clause, 'Only what changed since your last call, newest first', states the verb (retrieve changes), the scope (delta since a timestamp), and ordering. It also enumerates the change categories (headlines, analyst views, price moves, new/closing markets, trader moves), which makes it clearly distinct from the full-snapshot sibling problee_get_context, though that sibling is never named.

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

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

The description gives a concrete usage loop: 'Call again with since = the answer's until', which tells the agent exactly how to poll continuously. It also flags entitlement ('Plus and API Pro') and when to choose view=compact. It stops short of naming problee_get_context as the alternative when a full snapshot is wanted, or saying when not to use this.

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?

Far beyond what the annotations provide. It discloses engine-scoped approvals that drop out per settlement venue, that settlement-committed collaterals emit no approval (fills go on the commit ledger), that human identity is never chain-local periphery, and that addresses are UUPS/permanent. This is unusually rich 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 core purpose is front-loaded in the opening clause, but the remainder is a dense run-on covering approvals, settlement semantics, creator roles, and identity services. Much of it is useful, yet the lack of sentence breaks and mixed scope makes it harder to parse than it needs to 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?

An output schema exists, so return values need no explanation, and the description covers the behavioral complexity (approvals, settlement, permanence) thoroughly. It is complete for invocation, though the sprawl of tangential notes (identity service, cancel claims) dilutes rather than sharpens the essential guidance.

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

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

Schema description coverage is 100% for both optional filters (chainId, collateral), so the schema already documents them fully. The description's 'per-chain' and 'per collateral' phrasing aligns with the filters but adds no format or syntax detail beyond the schema. Baseline 3 applies.

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

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

The description states a specific resource set: per-chain collateral addresses (MarketRouter proxies, OutcomeToken1155, factories) plus the one-time trading approvals. An agent can tell this apart from list_collateral or get_factory_config by content, though it never names those siblings to explicitly disambiguate.

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 usage conditions: creator agents must pick a collateral with creation=true, cancellations and direct claims need no approval, and agents should verify against /trade/prepare or /trade/simulate rather than assuming permanence. It stops short of explicitly routing between this tool and sibling discovery endpoints.

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, so the safety profile is covered. The description adds real value beyond that by characterising the data as 'black-box public' and enumerating what is and is not returned (tiers, tier gates, public profile identity, evidence, freshness metadata), which tells the agent not to expect private or raw scoring detail.

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 sentences with the core purpose front-loaded and no filler. The second sentence partly restates what the output schema already declares, which is the only mild redundancy.

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

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

With an output schema, rich annotations, and a single fully-documented parameter, the description only needed to convey purpose and data expectations, and it does both. The remaining gap is sibling disambiguation, 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?

Schema description coverage is 100% and the single parameter (walletAddress) is fully documented with an EVM address pattern in the schema. The description adds no format, checksum, or chain-scoping detail beyond what the schema already states, so baseline 3 applies.

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

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

The description names a specific verb ('Read') and resource ('black-box public reputation for a wallet counterparty'), which is clearly distinct from self-reputation siblings like problee_get_my_reputation. However, it never names or distinguishes itself from close siblings such as problee_get_subject_reputation, problee_get_agent_reputation, or problee_batch_counterparty_reputation, so the agent must infer the boundary.

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 explicit when-to-use or when-not-to-use guidance. The phrase 'for a wallet counterparty' hints at scope, but nothing tells the agent when to pick this over the batch variant or the subject/agent reputation tools, which is the main decision facing a caller here.

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, so the safety profile is covered. The description adds a genuinely useful behavioral fact beyond them: both halves of the response are nullable and a between-seasons venue is a valid state, not an error — directly preventing a false failure interpretation of a null payload.

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

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

Two tight sentences, content front-loaded (season, cohort, then freeze/close times) with the nullability caveat placed last where it reads as a guardrail. Nothing is wasted.

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

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

With an output schema present, return shape need not be described, and the nullability note covers the main ambiguity for a zero-param read. The only gap is routing guidance against the several sibling season/cohort tools, which is not addressed.

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

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

Zero-parameter tool, so the baseline is 4. Nothing in the description is needed to clarify inputs, and it correctly adds nothing redundant.

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 specific resource returned: the open season, this week's scored question set, and the freeze/close times. An agent can tell this reads current season state, though the verb is implicit and it never distinguishes itself from nearby siblings like problee_get_season_cohort, problee_get_season_standings, or problee_list_scoring_cohort.

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 by 'to plan around', which suggests scheduling use, and there is no explicit statement of when to call this versus get_season_cohort or get_season_standings. No exclusions or prerequisites are given.

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/openWorld, so the safety profile is covered. The description adds genuinely new behavioral context: these are factory defaults read from live config and may not match a given market, which is a staleness/authority caveat not expressible in 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?

Two sentences, front-loaded with the core purpose and followed by the actionable caveat. The parenthetical enumerations are dense but each carries distinct information about lane-specific fee behavior 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 an output schema present, return values need not be described, and the description supplies the one thing the schema cannot: that these are defaults needing per-market verification. Complete for a zero-parameter, well-annotated read 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, so per the rubric the baseline is 4. The description correctly adds no parameter discussion and would gain nothing by doing so.

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 resource (canonical two-lane protocol fee schedule) and enumerates exactly what each lane covers (LMSR buy/sell+claim, ORDERBOOK place/taker fee/claim). It is clearly a read of factory-level fee defaults, though it never explicitly contrasts itself with the nearby problee_get_factory_config or problee_get_rules sibling.

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 routing guidance: treat these as DEFAULTS and confirm the per-market value via tradingRules on market detail or fee on problee_get_quote before executing. That names the alternatives and the condition that selects them, though it does not state when this tool itself should be skipped entirely.

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 substantial context beyond them: the free allowance resets every fixed seven days on the wallet's signup boundary, paidRemaining never expires, and at exhaustion cancellations, resting-order execution and verified full-position closes still work. That is exactly the operational behavior 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?

Information-dense and front-loaded: quantity first, then reset mechanics, then the exhaustion failure mode, then how to top up. A few clauses (e.g., the exact 'verified full-position closes' wording) are dense but each carries real behavioral meaning, so little 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?

For a zero-parameter read tool with an output schema already documenting return fields, the description covers scope, refresh cadence, exhaustion consequences, and the sibling that adds allowance. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description's discussion of freeRemaining, paidRemaining, period and resetsAt refers to response fields rather than inputs, so no parameter meaning is lost.

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 quantity and scope: 'How many executed wallet-sides this agent has left, including `freeRemaining`, and what buying PM adds.' Combined with 'Only PM markets read or debit this allowance,' an agent can tell this apart from balance or general account tools.

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

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

It gives clear context for when the result matters (at zero, a NEW PM order is refused with FILL_ALLOWANCE_EXHAUSTED) and points to problee_buy_play_money as the remedy. It stops short of explicitly saying 'call this before placing an order,' so the when-to-call trigger is implied rather than 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real context beyond that: the record is public, it is scored the same way for humans and agents, and it contains both open and settled forecasts. It says nothing about pagination behavior despite two cursor parameters, though the output schema carries 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?

Three short sentences, front-loaded with what the tool returns and its scope. The final disclaimer sentence is arguably filler but is short and does communicate intent, so waste is minimal.

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 a full-coverage schema, an output schema, and safe-read annotations already in place, the description only needs to convey scope and intent, which it does. The main residual gap is the lack of any routing signal against the very similarly named forecaster-record sibling.

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 three parameters are fully documented in structured fields, and the enum-free anyOf for address (wallet vs agent id) is explained there. The description's 'a person's or an AI agent's' reinforces the address duality but adds no syntax or pagination detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Read a forecaster's public record') and enumerates the contents: score against the price, open and settled forecasts, for both humans and AI agents. The purpose is unmistakable, but it does not differentiate itself from the near-identically named sibling problee_get_forecaster_record, 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 line 'A record, not a trade signal' implies a usage boundary, and 'Past performance is not indicative of future results' hints at interpretation, but neither states when to call this versus problee_list_leaderboard, problee_get_smart_money, or the similarly named sibling. Usage is only 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds meaningful context beyond them: the identity duality (wallet vs agent id), the GET /me reference, and the 12-settled-markets requirement before a score exists. No auth or rate-limit details, but it's a read with a rich output schema.

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

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

Three sentences, each earning its place: the resource and contents first, then the identity input rule, then the scoring threshold. The essential information is front-loaded with 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 read tool with a full output schema and complete annotations, the description covers the return content and a key caveat about verdict availability. Pagination is left to the schema's cursor fields, which is reasonable since the output schema exists and documents the cursor values.

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

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

Schema description coverage is 100%, so the schema already explains each parameter, including cursor fields that reference prior response objects. The description's clarification of wallet-vs-agent-id semantics adds some value over the schema, but the cursors go unmentioned. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description specifies a clear verb (read), resource (a forecaster's public record), and enumerates what the record contains: score, open forecasts, settled forecasts. This differentiates it from siblings like get_balance or get_positions. It doesn't name a specific sibling to contrast against, but the resource is distinctive enough.

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 clarifies the input selection rule (wallet address or agent id for agents without wallets) and notes the 12-settled-markets threshold before a verdict appears. However, it doesn't say when to choose this over list_leaderboard or get_positions, nor does it state when-not to use it, leaving alternative selection 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?

Beyond the read-only and idempotent annotations, the description discloses the counting rules that materially affect interpretation: one account counts once on its first settled call, voided markets never count, and Kellian-operated accounts are excluded by identity rather than name. These are substantive behavioral and domain constraints that the annotations do not provide.

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 one dense sentence but front-loads the resource and keeps every clause relevant to the counter, methodology, or exclusions. It could be split for readability, but there is little wasted wording.

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

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

With an output schema present, the description does not need to explain return values, and with zero parameters it does not need input guidance. It supplies the domain rules and exclusions necessary to interpret the counter correctly, making it complete for this tool's complexity.

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

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

The tool has zero input parameters, so there are no parameter semantics to explain and the baseline of 4 applies. The description adds no contradictory or unnecessary parameter information.

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 specific resource, the public launch counter, and precisely enumerates what it reports: settled calls in the season opening window, the methodology version, and signup grants held for review. This is far more than a tautology and gives an agent a distinct semantic identity among the many sibling 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?

Usage is implied by the explicit data content: an agent needing the public launch count, its methodology, or pending signup-grant review counts can identify this tool. However, there is no explicit when-to-use statement, no exclusions, and no named alternative or sibling to route against.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds a meaningful detail—each open option carries a condition id and a marketAddress that may be null—but says nothing about behavior on an unmatched or uncovered question, ambiguity resolution, or cost/latency of an open-world lookup.

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

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

Two sentences, usage trigger front-loaded, then purpose plus return shape; nothing is padding. The trailing parenthetical list of fields is dense but each item earns its place by telling the agent what it can answer with the result.

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 an output schema present, return values needn't be spelled out, and the read-only annotations cover safety, so the core is adequate. What remains missing is how the two lookup modes (address/chainId vs. question) behave differently, and what happens when the question is not covered—material for a 3-parameter, zero-required-argument tool with multiple entry paths.

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%: only `question` is documented, and its slug/Kellian/Polymarket-link formats come from the schema, not the description. The description contributes the important exclusivity hint ("Instead of address"), but `address` and `chainId` remain completely undefined in both places—an agent cannot tell whether `address` is a market contract address or a user address, or which chainId values are valid.

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?

Uses a specific verb and resource ("get detailed information about a specific prediction market") and enumerates the payload (condition id, price 0-1, 24h move, marketAddress), so the agent knows what comes back. It does not, however, distinguish itself from close siblings such as problee_get_market_state, problee_get_rules or problee_get_market_chart, which overlap in the "rules" and "state" territory it claims.

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 opening clause gives an explicit trigger—use it when a user asks for a market's odds, options, end date or rules—which is concrete and actionable. It stops short of exclusionary guidance: nothing says when to prefer problee_get_rules, problee_get_market_state or problee_list_markets instead, so the agent must infer the boundary.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds the useful default that the window is ALL when omitted, but says nothing about sampling frequency, number of points returned, or how the 'latest' frame interacts with the history series.

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 compact sentences with the core purpose front-loaded and the default window stated immediately after. The trailing 'Examples:' line is essentially a restatement of the same sentence and does not earn much space.

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 an output schema present, return shape need not be described, and the annotations carry the safety profile. However, for a 4-parameter tool with 25% schema coverage, the description leaves the address vs question selection and chainId semantics entirely to inference.

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% -- the schema documents 'question' (including the 'Instead of address' note) but leaves address and chainId bare. The description contributes only the default for 'window', and even that adds little since the enum already lists the accepted values; address, chainId, and address/question precedence remain 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 and resource -- 'Get price history + latest for a market' -- so the agent knows this returns historical series plus a current snapshot, which separates it from state/depth/holders siblings. It stops short of explicitly naming any sibling, so it is not fully disambiguated.

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 window options and a one-line example ('Read the 1D price history for a market') show how to call it, but nothing says when to prefer this over problee_get_market_state, problee_get_market_trades or problee_get_market_depth, nor any prerequisites.

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

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

Annotations already cover readOnly/idempotent/destructive/openWorld, so the bar is lower and the description still adds value: it distinguishes a simulated LMSR buy ladder from a live aggregated order-book snapshot and implies a point-in-time snapshot. It doesn't mention auth or rate-limit behavior, but the mode semantics are a genuine addition.

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

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

Two sentences, no waste, and the mode/discriminator detail is front-loaded before the routing hint to the sibling 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?

An output schema exists, so return-value detail needn't be in the description; what's left — the two possible depth shapes and where to go for full depth — is exactly what an agent needs to call this correctly.

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

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

Schema description coverage is 100%, so address/chainId semantics are already fully documented and the description adds nothing about them. The `kind` discriminator it mentions refers to the response shape rather than an input, so param-level value is baseline.

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

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

States a specific verb+resource (market depth, 5 levels) and names the two modes it can return, discriminated by `kind`. It explicitly situates itself against the sibling problee_get_orderbook, so an agent can tell them apart 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?

Frames itself as the 'discovery-sized view' and routes full-depth consumers to problee_get_orderbook, which is clear context. It doesn't state an explicit when-not condition (e.g. when depth beyond 5 levels is unnecessary), but the alternative routing 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 readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: what population is being measured (Kellian paper traders, not Polymarket traders) and how results are grouped (per outcome, expressed as open interest). It does not discuss scope limitations such as chains probed or data freshness, 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?

Two sentences, zero filler. The metric list is front-loaded and the disambiguation clause follows immediately, so the reader gets scope first and the most likely confusion point second.

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 an output schema present, the description need not explain return values, and annotations cover the safety profile, leaving little required. What remains is covered: what the tool measures and what it explicitly does not measure. A small gap is that it never states chain/coverage behavior, though the schema field for chainId handles that adequately.

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

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

Schema description coverage is 100%, with both 'address' (market contract address) and 'chainId' (probes enabled chains if omitted) fully documented, so the baseline is 3. The description reinforces the single-market scoping of 'address' but adds no format or behavior detail about chainId probing that the schema does not already carry.

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

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

States a specific verb-resource pair ('holders of one Kellian market') and enumerates the exact metrics returned: distinct holders, verified-human count, whale count, and total shares per outcome (open interest). It also draws an explicit boundary against the smart money lists, so an agent can separate it from problee_get_smart_money 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?

The closing sentence gives a clear exclusion rule: this is play-money/paper-trader data, not the Polymarket smart money data, which routes the agent away from problee_get_smart_money. It stops short of naming the sibling tool directly or describing the inverse case ('use X when you want real-money holders'), so it is strong context rather than a full when/when-not/alternative triad.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's value-add is the recency window (7 days), the newest-first ordering, and the explicit 'titles and links only' boundary with a not-advice disclaimer. That is genuine behavior beyond the annotations, though it says nothing about result volume, empty-result behavior, or whether openWorld fetching can be slow.

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 use-case trigger is front-loaded, followed by the payload description and two terse constraint sentences. Every sentence carries content; the field enumeration (title, link, outlet, label, matched terms) is the only slightly list-heavy part, and it is arguably redundant with the output schema.

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

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

An output schema exists and annotations are rich, so the description need not explain return values; it does need to cover the input pair and recency semantics, which it does. The remaining gap is chainId and the rule for which identifier is mandatory, leaving an agent guessing on a 3-parameter tool with zero required fields.

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 67%: address and question are documented in the schema, while chainId has no description anywhere. The prose mirrors the schema's address-vs-question split without clarifying whether both may be passed together or when chainId is required alongside address, so it adds little meaning beyond the structured fields.

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

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

The description gives a specific verb and resource ('Read a market's or a covered question's recent news headlines'), plus scope (last 7 days, newest first) and payload shape. It implicitly separates itself from the research/publish siblings via 'Titles and links only' and 'Research, not advice', but never names a sibling tool, so an agent must infer the boundary rather than being routed explicitly.

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

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

'Use this when someone asks for the latest news on a prediction-market question' is a concrete triggering condition, and 'Titles and links only' plus 'Research, not advice' set expectations about what this call will not deliver. There is no explicit when-not guidance or named alternative (e.g. get_market_research for deeper content), and nothing states that either address or question must be supplied even though requiredParameters is 0.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description earns credit for the extra behavioral facts: the call is creator-authenticated, invisible creator-deployed markets are explained only to the bound creator wallet, and other callers receive MARKET_NOT_FOUND. It does not mention rate limits or whether visibility results are cached.

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 is front-loaded and useful, but the 'Examples:' block is a semicolon-separated run-on whose clauses read as outcome fragments rather than parallel examples ('The event is over; the market is open on chain and takes no more trades'). It costs more parsing effort than the information warrants.

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 an output schema present, the description need not describe return values, and it covers auth scope, the not-found case, and the gating role. What remains thin is disambiguation from adjacent market-state tools, which matters given how many siblings exist.

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

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

Schema description coverage is 100%, with chainId and marketAddress both documented in the schema, so the baseline is 3. The description adds no further meaning about how the market address is resolved per chain or whether a mismatch is rejected.

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: a 'preflight' check of 'whether a market is visible and tradeable', narrowed to a 'Creator-authenticated' caller. It implicitly separates itself from read-only state fetchers like problee_get_market_state by framing the call as a gating check, but it never names a sibling, so the distinction from problee_check_market_exists must be inferred.

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?

'Preflight' plus the first example ('A visible live market can proceed to forecast and quote') gives a clear condition for calling it before trading/quoting. There are no explicit exclusions or named alternatives, and it does not say what to do instead when the market is not operable beyond the MARKET_NOT_FOUND note.

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, open-world access, so the safety profile is covered. The description adds that output includes dated research, sources and published takes, plus the disclaimer 'Research, not advice,' which is useful context. It says nothing about staleness, pagination, or what happens when no research has been published for a market.

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?

Short overall, and the trigger is front-loaded, but the second sentence is a run-on built from colon splices that take several reads to parse. The core fact — how the result changes for multi-option questions — is buried in the least parseable clause.

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?

An output schema exists and annotations carry the safety profile, so the remaining burden is addressing semantics, which the description partially covers. The unresolved gap is the multi-option fallback behavior, which is the main thing an agent needs to predict the shape of the response and is described only ambiguously.

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

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

With 75% schema coverage the baseline is 3, and the description earns above that by explaining the mutually exclusive addressing modes: a market address, a question by slug or Kellian/Polymarket link, or a single option by condition id, and it states the implicit rule ('Name the question or the option, not both') that the schema only partially encodes. It still doesn't explain what chainId governs or when it is required.

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

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

The description uses a specific verb+resource — 'Read dated research, sources and published AI analyst takes' for a binary market or one option — which distinguishes it from data-oriented siblings like problee_get_market_news or problee_get_question_forecasts. The second sentence's clause about multi-option questions is grammatically tangled ('a question of several options without one: each option's AI analysts and price'), leaving the fallback behavior somewhat opaque.

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?

'Use this when someone asks what the AI analysts expect on a prediction-market question, or for its dated research' gives a clear trigger condition. However, no alternative tool is named or excluded, despite obvious candidates in the sibling list (get_question_forecasts, get_market_news, get_forecaster_record), so the agent must infer routing itself.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail by noting that action details appear only when their public surface is available, which helps set expectations about conditional output.

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

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

The description is two concise sentences with no filler. The core state fields are front-loaded, and the conditional action-detail note is compact and informative.

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 an output schema present and full parameter descriptions in the schema, the description does not need to explain return values in depth. It adequately covers the tool’s purpose and the conditional availability of action details, though it still lacks sibling differentiation that would make selection fully unambiguous.

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

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

The schema has 100% description coverage for both parameters, including the market address and optional chainId behavior. The description does not add parameter-specific meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states that this tool returns per-market public resolution state, including stage, reason, deadlines, action flags, and final outcome. It uses specific resolution-state vocabulary, but it does not explicitly distinguish the tool from siblings like problee_get_market_state or problee_list_pending_resolution_markets.

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 implies the tool is for checking resolution state, but it gives no explicit guidance on when to use it versus related tools such as problee_get_market_state or problee_list_pending_resolution_markets. There are no stated prerequisites, exclusions, or alternative-selection criteria.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered without the description. The description adds nothing behavioral beyond the annotations -- no note on whether state is cached, how fresh the deadline/trading-end values are, or any latency/auth caveats. It only enumerates return fields, which the output schema already provides.

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?

One short sentence with zero filler and the key information front-loaded. It is appropriately sized for the tool, though the bare field list style leaves it feeling more like a schema echo than an orientation sentence.

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?

An output schema exists, so return values need not be re-explained, but the description still omits parameter guidance in the face of 0% schema coverage and gives no basis for choosing this tool over the several sibling market-state/read tools. For a tool in a crowded family, this is too thin to route an agent reliably.

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% for both parameters, so the description should carry the burden of explaining marketAddress and chainId. It mentions neither: there is no indication of the identifier format, or that chainId is optional and what the default chain is. The description therefore leaves the parameters entirely undocumented.

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

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

The description gives a clear verb ("Get") and names the specific state fields returned (marketState, lifecycleStage, stageDeadline, tradingEndsAt, outcome), which conveys the resource's nature. However, it reads as a field dump rather than a purpose statement and does nothing to distinguish it from near-neighbors like problee_get_market or problee_get_market_resolution_state, 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?

There is no when-to-use guidance, no condition under which this tool is preferred, and no mention of the overlapping siblings (get_market, get_market_resolution_state) that would be the natural alternatives. The agent is left to infer the choice entirely.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the newest-first ordering, which is genuine behavioral context, but it adds nothing about pagination, the limit default/cap, or chainId probing behavior.

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

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

A single tight sentence with the scoping key ('for a market') front-loaded. Its only inefficiency is enumerating return fields that the output schema already documents.

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?

An output schema exists, so return-value detail is redundant rather than necessary, and annotations cover safety. What is missing is paging/limit behavior and how this trade feed relates to the sibling fill/chart tools, which is material for a market-data query.

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 67%: address and chainId carry inline descriptions while limit has only a default/min/max. The description adds no parameter semantics (e.g., what limit does or how chainId omission is resolved), so it does not compensate for the uncovered parameter.

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 ('Recent trades for a market') and characterizes the return payload (side, size in wei, post-trade price, trader wallet). It does not distinguish itself from near siblings like list_trade_fills or get_market_chart, so a 4 rather than 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 offers no when-to-use guidance and names no alternative. It never explains the relationship to list_trade_fills (individual fills vs. trades) or get_market_chart, leaving the agent to infer routing on its own.

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