market_pulse_orderbook

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. The description adds value beyond annotations by disclosing the data source (Coinbase), the per-side depth cap (max 50), and the size cost of include_levels ('the ladder is `depth` pairs per side'), so the agent understands the verbosity trade-off of the heavy option.

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 definition is front-loaded with a dense, informative summary sentence followed by a clean Args block. The include_levels rationale is the longest part but earns its place by preventing an unnecessary heavy call, and no sentence 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 3-parameter read-only tool with an output schema and full annotation coverage, nothing needed to select and invoke it correctly is missing: source, return fields, parameter semantics, defaults, and the cost trade-off of the optional ladder are all covered. The only minor blemish is the schema title reading 'get_orderbookArguments' instead of matching the tool name.

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 fully compensates: symbol is clarified as the base ticker with examples ('BTC', 'ETH', 'SOL'), depth is defined as levels 'per side' with a max of 50, and include_levels explains its default-false behavior and the ladder cost. Every parameter gains meaning beyond the bare schema property names.

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

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

The opening sentence names a specific verb and resource — 'Get an order book snapshot for a crypto asset from Coinbase' — and enumerates the exact return fields (best bid/ask, spread in basis points, bid/ask volume imbalance over depth levels). This makes it easy to distinguish from siblings like market_pulse_price or market_pulse_summary, which cover single quotes and aggregate views rather than ladder depth.

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 clear context on what the tool returns and says the summary fields 'answer most questions', with include_levels to be enabled 'only to walk the book or size an order against real resting liquidity'. It provides clear context without explicit exclusions, but it never names an alternative sibling or states exactly when to pick this over market_pulse_price or market_pulse_summary.

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