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.

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals determinism, cost, authentication requirements (WALLET_PRIVATE_KEY, USDC on Base), and the date-seeding logic. It does not describe the return format or error behavior, but for a simple tool with one optional parameter, this coverage is strong.

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 sentences, front-loaded with the primary purpose, followed by cost and prerequisites. Every word earns its place, with no redundancy or 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 tool with one optional parameter, no annotations, and no output schema, the description covers the core behavior, cost, and authentication. It could mention the return format explicitly, but the phrase 'book pick' sufficiently implies the output for a user familiar with the corpus.

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 covers 100% of parameters with a description for 'date'. The description adds context by linking the date to UTC day and backfill, but it largely restates what the schema already provides. Baseline 3 is appropriate since the schema carries the semantic weight.

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 the tool's function: a deterministic daily book pick from the indexed corpus, date-seeded for consistency. It distinguishes itself from siblings by emphasizing deterministic behavior and UTC date seeding, which is unique among the listed search and metadata 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?

The description explains when to use the tool (to get the daily book pick) and mentions the optional date override for backfilling past days. It does not explicitly name alternatives, but the deterministic daily pick function is distinct enough that clear exclusion criteria are unnecessary.

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?

No annotations are provided, so the description carries the full burden. It discloses important behavioral traits: the tool costs $0.003 via x402, requires WALLET_PRIVATE_KEY and USDC on Base, and returns a ranked list of books. It also mentions the shelf catalog URL for discoverability. The description does not explicitly state it is read-only, but the purpose and output format imply a safe browse operation.

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 concise and front-loaded with the tool's primary purpose. The subsequent sentences add essential operational details (return format, catalog URL, cost and requirements) without unnecessary fluff. The longer category list is justified as it directly informs valid parameter values.

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 simplicity (one parameter, no output schema), the description is complete: it explains what the tool returns, how to discover available shelves, and the cost/auth requirements. It also implicitly ties into sibling tools by mentioning 'book_id for drill-down', which supports the overall workflow.

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 covers 100% of the parameter with a description, but the tool description adds significant value by enumerating example shelves (e.g., 'gothic-fiction', 'russian-literature') and clarifying that there are 100+ auto-generated shelves beyond the 10 hand-picked ones. This goes beyond the schema's basic example of 'gothic horror' or 'russian-literature' and enriches the agent's understanding of valid inputs.

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 the tool browses a curated category/subject shelf and returns a ranked list of books with book_id for drill-down. It distinguishes itself from sibling search tools by explicitly mentioning curated shelves and listing specific categories, making the scope and resource clear.

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 provides clear context for when to use this tool: to browse curated shelves rather than perform a general search. It also hints at the next step (drill-down with book_id) and mentions the shelf catalog is discoverable at a URL. However, it does not explicitly state exclusions or directly compare with alternatives like search_books, so it falls slightly short of a perfect score.

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?

No annotations are provided, but the description discloses the cost ($0.002), payment method (x402, USDC on Base), wallet requirement, and lists the return fields. This is substantial context for a read-only metadata operation, though it omits error handling 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?

Two concise sentences: the first defines the tool's scope and outputs, the second provides prerequisite and cost. Every sentence carries meaningful information with no 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?

For a single-parameter tool with no output schema, the description covers inputs, outputs, prerequisite (search_books first), and cost/payment details. It is sufficient for an agent to select and invoke the tool correctly, though it does not specify the exact return format.

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% and the schema already describes book_id as 'Gutenberg book id, from search_books.' The description adds 'indexed book' and integer context but does not materially improve parameter understanding 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?

Description states 'Full metadata for one indexed book by book_id' and enumerates specific fields (title, author, year, subjects, etc.), making its purpose unmistakable and distinguishing it from siblings like get_chapter and search_books.

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?

Provides explicit prerequisite: 'Use search_books first to find a book_id.' Also adds cost and wallet requirements, giving clear context for when it should be invoked. It does not explicitly name alternatives to avoid, but the coverage is strong.

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?

With no annotations, the description takes on the full burden. It discloses meaningful behavioral traits: chapter 0 is front matter, the operation costs $0.005 via x402, and it requires WALLET_PRIVATE_KEY with USDC on Base. It does not cover potential errors or return format, but the special-case and payment details exceed baseline expectations.

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 three sentences, front-loaded with the core action. Every sentence earns its place: sentence 1 states purpose, sentence 2 clarifies an edge case, sentence 3 gives usage guidance and cost. No redundant or filler content.

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 tool with only two params and no output schema, the description covers the essential context: what is returned ('full text'), the special chapter-0 case, cost, auth requirement, and a pointer to the metadata tool for range validation. It does not describe error behavior or response format, but these are somewhat implicit given 'full text' and the overall simplicity.

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 description only needs to add marginal value. It slightly reinforces the meaning of 'chapter' by restating 'Chapter 0 is front matter' (already in the schema) and mentions book_id/chapter, but adds no new parameter-level syntax or format details 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 opens with a specific verb+resource: 'Full text of one chapter from an indexed book by book_id and chapter number.' It clearly distinguishes this tool from siblings by focusing on retrieving chapter text, and explicitly directs users to get_book_metadata for range validation.

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 when to use the tool (to retrieve full chapter text) and even names an alternative for a related task ('Use get_book_metadata for the valid chapter range'). It also notes the payment requirement and cost, which implies usage constraints. However, it doesn't explicitly state when not to use this tool (e.g., when only metadata is needed), leaving that slightly 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?

With no annotations, the description carries the full burden. It discloses cost, required credentials (WALLET_PRIVATE_KEY, USDC on Base), and the behavioral difference between full-text search and sample output. However, it does not describe the return format, pagination, or error 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?

Two compact sentences, front-loaded with the core purpose, then the optional search behavior, then cost and prerequisites. No filler or 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?

For a 3-parameter tool with no output schema, the description covers purpose, optional behavior, and critical payment/auth requirements. It doesn't state return type or error scenarios, but given the simplicity and intuitive nature of quotes, it's adequately complete.

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 adds value by clarifying that omitting theme returns a sample of short dialogue-bearing lines and that theme enables full-text search within the book, enriching the schema's terse 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 indicates the tool returns notable passages from a specific indexed book via book_id. It distinguishes from siblings by emphasizing book-specific retrieval and optional full-text theme search, though it lacks an explicit verb like 'retrieves' or 'lists'.

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 tool explains parameter usage (optional theme vs default sample) but does not give any guidance on when to prefer this tool over siblings like search_books or get_chapter. No exclusions or alternative tools 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?

With no annotations, the description carries the full behavioral burden. It discloses cost ($0.005 via x402), required WALLET_PRIVATE_KEY, and USDC on Base, which is important. However, it omits other behavioral details such as rate limits, error handling, or whether the search is read-only, leaving gaps in transparency.

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 sentences, front-loaded with purpose and example, followed by return behavior and cost. Every sentence earns its place without unnecessary detail or fluff.

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 two parameters, no output schema, and no annotations, the description covers the key aspects: search method, examples, ranking, book_id for drill-down, and cost. It does not explain pagination or response format, but for a search tool with simple parameters, it is reasonably complete.

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 adds examples ('Dickens', 'Frankenstein') and clarifies substring matching, but these are minor enhancements over the schema's existing descriptions. It does not add significant meaning to limit 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 clearly states the tool's action ('Search'), resource ('indexed public-domain book corpus'), and method ('by title or author substring'), with concrete examples. It also distinguishes itself from siblings by noting it returns book_id for drill-down into metadata, chapters, quotes, or full-text search, positioning it as the entry point to related 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?

The description implies usage context by mentioning drill-down capabilities, but it does not explicitly state when to use this tool over siblings like search_literature or get_book_metadata. There is no 'when-to-use' or alternative recommendation, so guidance is only 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?

With no annotations provided, the description fully discloses key behaviors: it is retrieval-only (never generates or summarizes), costs $0.02 via x402, requires WALLET_PRIVATE_KEY and USDC on Base, and returns real cited passages ranked by relevance. This is transparent about cost, authenticity, and prerequisites.

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 concise (three sentences) and front-loaded with the core purpose immediately. Each sentence adds distinct value: scope, output, and cost/authentication. No filler or 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?

The description provides sufficient context for a search tool: what it searches, what it returns, cost, and required credentials. It lacks details about search behavior (e.g., stemming, matching) but compensates with strong purpose and transparency. Given the simple schema and no output schema, this is nearly complete.

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 parameters (query and limit). The description does not add extra semantic detail beyond what the schema already provides, such as query syntax or behavior for varying limits, so the baseline of 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 clearly states a specific verb and resource: 'full-text search across the entire indexed public-domain corpus.' It distinguishes itself from sibling tools by emphasizing the full-text nature and the 'PREMIUM' aspect, likely different from search_books which may search metadata. The scope and output (passages with citations) are 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 usage for full-text retrieval but does not explicitly state when to prefer this over alternatives like search_books. It provides context (premium, full-text, cost) but no exclusions or alternative references, so guidelines are implied rather than explicit.

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