ask_book

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

With no annotations, the description carries full weight. It discloses key behaviors: retrieval-only (not a summary), chapter/location citations, cost of $0.01 via x402 requiring WALLET_PRIVATE_KEY and USDC on Base, and flexible book name resolution. This is actionable operational context beyond what the schema 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?

The description is somewhat long due to the necessary list of available books, but every sentence serves a purpose: purpose, retrieval nature, name resolution, and cost. It is front-loaded with the main action and avoids redundantly repeating schema details. The book list is essential even though it adds length.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description is comprehensive. It covers what it does, how to use it, pricing/auth requirements, and what it returns (passages with citations). The only minor gap is error handling for unrecognized book names, but the description's 'any recognizable name... resolves' implies robust matching.

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 covers all 3 parameters with descriptions, so baseline is 3. The description adds value by explaining that 'book' accepts any recognizable name and resolves to the matching route, supplementing the static list in the schema. It also reinforces that 'limit' is optional, though the default/max are already in the schema.

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

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

The description uses a specific verb ('Ask') and resource ('flagship books'), and clearly states the output: 'most relevant passages from the book itself, with chapter/location citations.' It distinguishes itself from siblings like search_books and get_quotes by emphasizing natural-language questions and the retrieval-only nature.

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 provides clear context: use for natural-language questions about flagship books to get passages. It also gives an exclusion—'Retrieval only — never a generated summary'—which tells the agent not to use it if a summary is needed. However, it does not explicitly name alternative tools or state when to prefer search_books or get_quotes.

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