Prediction-market quote

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces no state mutation. It adds significant behavioral context: explains the openBlocked mechanism (preview of potential open rejection with reason codes), side behavior (NO fills at 100 minus probability), paper trading constraints, execution costs, and lack of fill guarantee. No contradictions.

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 quite long (multiple paragraphs) but is well-structured: it front-loads the main quote components, then explains side behavior, paper trading details, and execution costs. Every sentence adds information, but some parts (like execution cost details) could be more concise. Still, it earns its length given the tool's complexity.

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

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

The description covers the return fields (entry probability, share estimate, max payout, etc.) and explains openBlocked/reasons. It addresses safety (read-only), side mechanics, and paper trading constraints. An output schema exists (not shown) but is referenced. No obvious gaps for a quote tool, though it could mention any rate limits or pagination if applicable (likely not).

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%, but the description adds value beyond schema: it clarifies stakeMusd minimum (min to open is 10), explains side behavior in depth, and describes agentTrace as stored private metadata. This extra context aids understanding beyond the schema descriptions.

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 it's a read-only PM quote for a binary outcome, listing specific fields returned. It contrasts with open_pm_position by explaining the openBlocked field, which previews potential rejection. The tool name and sibling tools (futures_quote, spot_quote) provide context, but the description itself makes the purpose unambiguous.

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 explicitly states it is read-only and never mutates state. It provides conditions like stakeMusd must be > 0 (min 10) and explains side parameter behavior. It contrasts with open_pm_position via openBlocked, indicating when to use this quote before attempting to open. However, it does not explicitly differentiate from other quote tools (futures_quote, spot_quote), though the PM specification and sibling context make this clear.

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