stacks_market_quote_buy

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

With no annotations, the description carries the full burden and does add real value: it discloses the return unit (micro-STX), the pricing model (LMSR), and a hard constraint (mainnet only). It stops short of stating that this is a read-only view call requiring no gas or signature, and says nothing about quote freshness or slippage.

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

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

Purpose and return value are front-loaded and the mainnet caveat is short and useful. The trailing 'Tip: call earning_opportunities…' is promotional and does not earn its place in a quoting tool's description.

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

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

For a 3-required-param, no-output-schema tool, the description covers what is needed: what it computes, what it returns and in what units, and a network constraint. Missing only quote-validity/slippage semantics that would matter before placing an actual order.

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; the description's 'Side: 0 = YES, 1 = NO' simply repeats the schema. It adds no new detail for market_id (epoch-ms) or shares units beyond what the schema states, 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: 'Get an LMSR buy price quote for YES or NO shares on a Stacks Market prediction market.' The word 'quote' implicitly separates it from execution siblings like stacks_market_buy_yes/buy_no and from stacks_market_quote_sell, but no sibling is 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 by the word 'quote' — an agent can infer it should be called before buying, but the description never says 'use this to preview cost before stacks_market_buy_yes/buy_no' or state any exclusions. The 'Tip' about earning_opportunities is unrelated to when to use this tool and does not count as guidance.

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