ReadingRate

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

Annotations already declare non-readOnly, openWorld, idempotent, non-destructive, so the bar is lower, but the description adds substantial context beyond them: an already-present book is left in place and the result reports its shelf, read status triggers an activity feed entry with privacy caveats, and title/author misses fall back to Google Books which makes the catalog entry public. It does not spell out auth needs or rate limits, so 4 rather than 5.

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?

Front-loaded with the core action and the status variants, then routing, then side effects, then examples. Every sentence carries distinct information, though the side-effect paragraph is dense and the description runs long for a 6-param tool with full schema coverage.

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?

With an output schema present the description needn't document return values, yet it still tells the agent the result reports which shelf the book landed on. Combined with the fallback behavior, privacy defaults and exclusivity rule, nothing an agent needs to call this correctly is missing.

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, but the description contributes a constraint the schema lacks entirely: identify the book with exactly one of book_id, isbn or title_author. It also explains that status overrides the default want-to-read shelf and that rating/date_finished apply only to read status, adding real meaning on top of the enum.

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 (adds one book to the reader's library) and immediately scopes it against the closest sibling by naming update_book_status for moving and implying add_matched_books_to_library is the batch variant. An agent can distinguish it without opening the schema.

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?

Explicitly states when to use (user asks to add a book, or says they are reading/finished a book not in their library), the alternative for the move case (update_book_status), and a prerequisite (confirm the title before adding a title-only book). Nothing is left to inference.

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?

Annotations cover safety hints (idempotent, non-destructive), and the description adds genuinely non-obvious behavior: the 40-book cap, the want-to-read default, that already-present books are left in place and reported back, and that 'read' books publish to the activity feed subject to profile privacy defaults. Nothing contradicts the annotations; the idempotent hint is consistent with 'left where they are'.

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?

Front-loaded with purpose and cap, then selection guidance, then side effects, then an example — a sensible order with no filler. The activity-feed/privacy sentence is long and heavily nested, which costs a little readability.

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?

An output schema exists, so return values need no explanation; the description still covers inputs, cap, default shelf, duplicate handling, downstream visibility, and the sibling alternative. For a 2-parameter mutation tool this is complete enough to call correctly on first try.

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% (including the status enum and the 40-max on book_ids), so the baseline is 3, but the description adds that status applies uniformly to every newly added book and that absent status means want-to-read. The concrete JSON example reinforces the shapes. Minor gap: it does not explain what happens when book_ids exceeds 40.

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 first sentence states a specific verb (adds), resource (books to the reader's library), scope limit (up to 40, one call), keying (by ReadingRate book id), and default shelf behavior. It is clearly distinguishable from add_book_to_library (single, unmatched books) and lookup_books_batch (matching, not adding), both of which it names.

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?

Explicit routing: use after lookup_books_batch has matched a shelf or list and the reader has chosen which books to add; unmatched books go through add_book_to_library once the title is confirmed. It also states the tool never adds to the catalog, an explicit when-not condition.

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?

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description adds real value on top: 'Each call adds a new note' spells out the append/non-idempotent behavior in plain terms, and 'The line is not saved as a quote' clarifies the side-effect boundary. It stops short of describing failure modes or what happens on a bad anchor, so not a 5.

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?

Front-loaded purpose sentence, then usage, then the alternative, then a compact example. Every sentence carries a distinct fact (destination, exclusion, append semantics, format) with no repetition.

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 2-parameter write tool with an output schema and full annotation coverage, this covers what an agent needs: where the note goes, that it is not a quote save, that calls accumulate, and a concrete anchor example. Return values are handled by the output schema, so no further detail is required.

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 worked example {"anchor": "wyatt/whoso-list-to-hunt/13", "note": "..."} goes beyond the schema by demonstrating the concrete anchor format, which the schema only describes abstractly as 'as get_poem or search_poems returns it'. The note parameter itself gets no extra semantic guidance.

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 (writes) and resource (the reader's note on one line of a poem) plus the destination (ReadingRate notes). It also names the adjacent concept it is not — 'The line is not saved as a quote' — and points at save_poem_line, so an agent can distinguish it from siblings without opening schemas.

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?

Gives an explicit trigger ('Use when the reader wants to record a thought about a specific line of a poem') and an explicit alternative with its selecting condition ('To save the line itself as a quote, use save_poem_line'). Nothing is left to inference.

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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds useful behavior: the output is a comparison grid, the input is capped at two or three books, and it declares the default aspects. It does not discuss pagination, rate limits, or failure behavior for unknown slugs, keeping it short of a 5.

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?

Front-loaded with the core action, then aspects, then usage routing, then compact examples — each block has a distinct job. No sentence is redundant, and the aspect glossary replaces what would otherwise be vague enumeration.

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?

An output schema exists so return values need no explanation, and the description closes the remaining gaps: the 2–3 book limit, defaults, aspect meanings, and sibling routing. For a two-parameter read-only compare tool this is fully sufficient to invoke correctly.

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 already 100%, yet the description goes well beyond it by defining what each aspect actually yields: 'difficulty' includes overall and per-dimension scores plus hardest/easiest dimensions, 'themes' splits shared vs distinct, 'length' gives word count and reading time, 'style' covers genre and literary regard. Two concrete call examples show the id-array shape and default-vs-explicit aspects.

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 ('Sets two or three books side by side and shows them as a comparison grid') and enumerates exactly what is compared via the five named aspects. It is immediately distinguishable from sibling read tools like get_book_details 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?

Explicitly states when to use it ('compare specific books, which of them is harder or longer, or which to read first') and routes to the correct alternatives for adjacent intents: get_book_details for a single book, search_books to find books. Nothing is left to inference.

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?

Annotations already declare destructiveHint=true and idempotentHint=true, yet the description adds non-obvious semantics annotations cannot convey: irreversibility, that the attached conversation record is deleted too, and that a copy already sent to the reader's Notion survives outside ReadingRate. That partial-deletion behavior is exactly the kind of context an agent needs before confirming a destructive call.

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 destructive verb and irreversibility lead, followed by the Notion caveat, then usage guidance and an example. Four short sentences, each carrying distinct information, with nothing repeated.

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?

An output schema exists so return values need no elaboration, and the description still notes that the result reports the surviving Notion copy. For a destructive single-parameter tool it covers impact, prerequisite lookup, and confirmation, leaving no gap an agent would need to guess at.

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 description already explains that the id comes from get_reading_notes or save_reading_insight, so the description largely restates it. The inline example {"insight_id": "<insight id>"} adds a little formatting guidance but no new semantic depth, which matches the baseline 3 for a fully documented single parameter.

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?

Opens with a specific verb and resource ("Permanently deletes one reading insight the reader saved in ReadingRate") and immediately scopes the blast radius ("with the conversation record attached to it"). It is unambiguously distinct from save_reading_insight and get_reading_notes among the siblings.

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?

Gives an explicit trigger ("when the reader asks to delete or forget an insight they saved"), an explicit prerequisite lookup path ("Find its id with get_reading_notes"), and an explicit safety step ("confirm with the reader which insight they mean before deleting"). No inference required.

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?

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so safety is covered. The description adds genuinely non-structured behavior: matching is semantic ('closest in meaning') rather than keyword, it spans all of the reader's books, and results carry a 0–1 similarity score. It omits cost/latency expectations for an embedding-style search, but the semantic-matching trait is the key behavioral disclosure.

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?

Front-loaded with purpose and scope, followed by the when-to-use and id-provenance sentence, then concrete examples. The opening sentence is dense and front-loads return fields that the output schema already covers, but no sentence is filler and the examples earn their place.

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?

An output schema exists, so the description does not need to detail the response, and all four parameters are schema-documented. Combined with the explicit trigger and id-source routing, an agent has everything needed to call this correctly without further inference.

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% and every parameter (id, type, limit, threshold) is documented, including defaults and max, so baseline 3 applies. The description adds only the id-provenance mapping (quote id from list_saved_quotes, note id from get_reading_notes) and two call examples, which largely restate the schema rather than adding new semantics.

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 — 'finds the quotes and notes... closest in meaning to one of their saved quotes or notes' — plus scope ('across all their books') and the result shape (book, author, page, similarity score). An agent can distinguish this semantic-similarity lookup over the reader's own collection from search_book_content or get_passages_near_reading_position without opening a schema.

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?

Gives an explicit trigger ('Use when the reader asks what else they have saved that connects to a particular quote or note') and names the prerequisite source tools: list_saved_quotes for a quote id, get_reading_notes for a note id. It stops short of stating when NOT to use it or contrasting it with the closest sibling, get_passages_near_reading_position, so it lacks full exclusion guidance.

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?

Beyond the read-only, idempotent annotations, the description adds meaningful behavior: results are grouped by year newest first, source_type defaults omit curricula unless explicitly requested, each book carries award_type and award_kind, and curricula are study sets not prizes won. It also adds the linkage to ReadingRate analysis, which is external context the annotations cannot provide.

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 what the tool returns, followed by usage guidance, parameter nuances, and examples. The prize enumeration and examples are dense but each earns its place by helping the agent recognize and route relevant queries without scanning the schema.

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 six-parameter, read-only browsing tool with full schema coverage, rich annotations, and an output schema, the description covers purpose, usage triggers, exclusions, default filtering behavior, source-type distinctions, and examples. Nothing essential is missing for correct invocation.

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 parameter descriptions already carry the baseline semantics. The description adds value by explaining the default source_type behavior ('prizes and lists come back and curricula do not') and by providing concrete examples that clarify how award, year bounds, and source_type combine.

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 and resource: lists winners, shortlists, and longlists of tracked literary prizes, grouped by year newest first. It names the covered prizes and clarifies that each book links to its ReadingRate analysis, so the agent can distinguish this from book-detail or search tools without opening schemas.

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 clearly states the triggering use cases: asking who won or was shortlisted, finding prize-winning books across years, or identifying books named by a list or syllabus. It also excludes news about prizes or organizations, but does not name a sibling alternative when a user needs general book search instead.

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?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral value by bounding the response (exactly five most recent books, member usernames and roles) and by naming the required upstream call for club_id. It omits any note on what happens for invalid or inaccessible club ids, which keeps it below a 5.

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?

Three compact sentences plus one example, front-loaded with the capability statement before usage and invocation details. Every sentence carries distinct information: what it returns, when to call it, and where the id comes from.

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?

A single-parameter read tool with an output schema, full schema coverage, and rich annotations needs little more. The description still tells the agent what the payload contains and how to obtain the required id, leaving nothing essential unstated.

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 single parameter has 100% schema description coverage and the schema already says 'from list_book_clubs,' which the description simply restates. The added JSON example shows the call shape but conveys no new meaning about the parameter's format, source, or failure modes. Baseline 3 is correct when the schema does the work.

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?

Opens with a specific verb and resource ('Describes one of the reader's ReadingRate book clubs') and then enumerates exactly what is returned: description, member count, usernames and roles, and the five most recent books. That enumeration also implicitly separates it from list_book_clubs (ids only) and get_book_club_current_read (current book only), so an agent can pick it without opening the schema.

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?

Explicit trigger: 'Use when the reader asks about a particular club of theirs: who is in it, or what it has read,' plus the prerequisite chain 'Get club_id from list_book_clubs.' It does not state when NOT to use it or name get_book_club_current_read as the alternative when only the in-progress book is wanted, so it stops short of full routing guidance.

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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds useful behavioral context by describing the returned schedule shape (milestones with pages, due dates, discussion questions) and the dependency on a club id from another tool, though it says nothing about what happens when a club has no active read or an invalid id.

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?

Three short sentences plus an example, with the return contents front-loaded and the prerequisite last. Nothing is redundant or padded.

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?

With a full output schema present, the description need not explain return values, yet it still summarizes the payload well enough for the agent to know when this tool answers the user's question. One required parameter, documented provenance, and a usage example leave no meaningful gap.

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 single parameter already has 100% schema description coverage ("The club's id, from list_book_clubs"), so the schema does the heavy lifting. The description largely repeats that provenance and adds only a minimal call example, which is marginal value over the structured fields.

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 names a specific verb and resource ("Returns the book one of the reader's ReadingRate clubs is reading now") and enumerates exactly what comes back: each milestone's pages, due date and discussion questions. That content profile cleanly separates it from the broader get_book_club sibling without needing to mention it by name.

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 gives three concrete triggering questions ("what their club is reading, how far they should be by now, or for the discussion questions") plus the prerequisite routing instruction "Get club_id from list_book_clubs", which names the exact sibling that supplies the required argument.

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?

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds valuable context about the return content (e.g., radar chart scores with written reasons, awards vs. taught_in distinction) and includes examples of parameter usage, though it does not discuss error cases or rate limits.

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 well-structured with front-loaded purpose, followed by usage guidance, identification rules, dimension explanations, and examples. While comprehensive, the list of difficulty and regard dimensions is somewhat lengthy; however, each part serves a clear purpose in helping the agent understand the tool's output.

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 complexity (many dimensions, nested parameters) and the presence of an output schema, the description provides ample context about what the tool does and when to use it, including all necessary constraints and alternatives. Nothing critical for correct invocation is missing.

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 schema describes each parameter. The description adds the crucial constraint that exactly one of book_id, slug, or title_author must be provided, which is not enforced by the schema (none are required). It also implies the optionality of include_similar and include_time_estimate through examples but doesn't elaborate beyond 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 the tool provides a book's full ReadingRate analysis, including a difficulty profile as a radar chart with nine difficulty and four literary-regard dimensions, plus metadata like description, genres, word count, etc. It distinguishes itself from siblings by explicitly naming search_books for finding books and compare_books for side-by-side comparison.

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 gives explicit usage scenarios: when the user asks about difficulty, reading time, awards, or details about a specific book. It also names alternatives (search_books for discovery, compare_books for comparison) and states the identification constraint (exactly one of book_id, slug, or title_author).

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?

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered by structured data. The description's added value is modest but real: it says the pace basis is the user's own logged reading speed and that the result is scoped to their ReadingRate library. It says nothing about what happens with no books in progress (empty list vs error) or about pagination/result size.

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?

Three short blocks in a deliberate order: what it returns, when to call it, when to call something else. Every clause carries information, including the pace qualifier, and there is no filler or restatement of the title.

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?

Zero parameters, an output schema that documents the return shape, and annotations covering idempotency and read-only safety mean the description only has to explain scope, contents and routing — all of which it does. An agent has everything needed to select and call it correctly.

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 tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description's implicit scoping (the caller's own library) is consistent with there being no filtering 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?

States a specific verb and resource ('Lists the books the reader is reading now') and enumerates exactly what comes back: current page, percent complete, pages left, and hours left at the reader's own logged pace. It also discloses a non-obvious inclusion (recently re-read poems with counts) and explicitly names the sibling it is not (get_reading_history), so an agent can separate it from the many other reading 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?

Gives three concrete user-intent triggers ('what they are reading', 'how far along', 'how long ... to finish') and an explicit exclusion plus alternative: 'For books they have finished or want to read, use get_reading_history.' Nothing about routing is left to inference.

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?

Goes well beyond the annotations by disclosing the non-obvious write behavior: the first call each day sends passages to an AI provider, generates and stores the result in the reader's account, and counts against their AI usage quota, while later calls return the same data. This explains exactly why readOnlyHint=false while idempotentHint=true, and pre-empts surprises about quota consumption.

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?

Front-loaded with the return value, followed by the side-effect/idempotency fact, then a final usage sentence. Every clause carries information absent from the schema or annotations; the AI-provider detail, though wordy, is precisely the hidden cost an agent needs.

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?

An output schema exists, so the description need not enumerate return fields, yet it still characterizes the shape (theme plus question). Combined with the disclosed first-call generation and quota counting, an agent has everything needed to decide whether to call and what to expect.

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 tool takes no parameters, so there is nothing to disambiguate beyond confirming the implicit 'today' scoping, which the description does make clear. The zero-parameter baseline of 4 applies; no additional per-argument meaning is possible.

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 ('returns today's connections in the reader's reading') and then concretely describes the payload: passages from different books, saved quotes, a named theme, and a reflection question. This is distinguishable from siblings like find_related_passages or compare_books, which operate on explicit inputs rather than the reader's current multi-book state.

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?

Explicitly names the trigger: 'Use when the reader asks what connects their recent reading, or for today's reading connections or reflection prompt.' That is a clear usage context, but it stops short of naming alternatives or exclusions (e.g., when to prefer find_related_passages for a targeted passage lookup).

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds genuinely useful behavior the annotations cannot express: 'Summaries are made after each month ends', which warns the agent that a not-yet-complete month may have no summary. It stops short of saying what is returned when no summary exists yet.

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?

Three short units — what it returns, the availability caveat, when to use it and what to use instead — front-loaded with the scoping constraint. The example is compact and every sentence earns its place.

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?

With an output schema present, the description needn't explain return structure, and it still summarizes the payload. Combined with rich annotations and full parameter documentation, an agent has everything needed to choose and call this correctly.

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% (both year and month are documented with ranges and formats), so the baseline is 3. The description only restates the shape in an example call ({"year": 2026, "month": 9}), which illustrates usage but adds no semantics 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?

States a specific verb and resource ('Returns ReadingRate's summary of one calendar month of the reader's reading') and enumerates the contents: books finished, time/pages, difficulty, highlights, and year-to-date comparison. That scope statement plus the named alternative makes it unmistakable against summarize_reading_period or get_reading_stats.

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?

Explicitly gives the selecting condition ('Use when the reader asks how a particular month of reading went') and names the sibling plus the condition that selects it ('For any other range of dates, such as a year or a season, use summarize_reading_period'). No inference required.

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive behavior. The description adds meaningful non-obvious context: text availability is limited to books the reader uploaded, and unavailable text is reported in the result with book analysis routed to get_book_details.

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?

Front-loaded with what it returns, then usage guidance, then availability constraints and examples. It is somewhat verbose, but the structure is clear and each paragraph serves a distinct purpose.

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?

Complete for an agent: it covers retrieval scope, automatic position detection, topical filtering, when to use it versus a sibling, data availability limits, and fallback behavior. An output schema exists, so return-value detail is not required.

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%, so both parameters are already documented in the schema. The description adds useful framing about automatic book/page discovery and topical focusing, but does not add format or edge-case detail 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?

States a specific verb and resource: returns text passages near the reader's current position in ReadingRate. It also distinguishes itself from search_book_content and get_book_details by explaining what it does versus those siblings.

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?

Explicitly says when to use it: when the reader asks about what they just read, a recent passage they did not understand, or the part they have reached. It also names the alternative, search_book_content, for whole-book topical search.

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?

Annotations already declare readOnly, idempotent, closed-world, non-destructive, so the safety bar is low; the description earns credit by adding real behavior beyond that — finished books are excluded, each pick arrives with reasons and a pace-based reading-time estimate, and the pool is the catalog. It does not mention latency, cost, or fallback behavior if the reader has too little history.

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 matching criteria are front-loaded in the first sentence, followed by constraints and a usage cue, with compact examples that demonstrate parameter combinations rather than restating the schema. The first sentence is dense with a long list, but no sentence is redundant.

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?

With a full output schema and complete annotations, the return-shape burden is off the description, and what remains — personalization signals, exclusions, the three mode flags — is covered. The one missing piece is a pointer to when a plain catalog search is the better call, which matters given how many search/read siblings exist.

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 prose adds nuance the schema lacks, specifically that difficulty_stretch reaches only 'a little above' the usual range, that from_tbr restricts the candidate pool rather than ranking it, and the examples demonstrate combinations. The count/default-max is left to the schema, which is fine.

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 and resource ('Recommends books from the ReadingRate catalog') and immediately scopes it to 'this reader' with named matching signals (difficulty range, genres/themes, reading pace). That clearly separates it from the catalog-search sibling search_books, which has no reader-personalization framing.

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?

'Use when the reader asks what to read next, or which books would suit them' gives a clear triggering intent, and the three examples show default, TBR-only, and stretch/exclusion configurations. It stops short of naming alternatives (e.g., search_books for a keyword lookup) or stating when not to use it, so it is clear but not exhaustive.

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?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), so the lower bar is met and the description adds genuinely non-obvious behavior: numbered-line output, titles/epigraphs/dedications/stage directions separated from verse, and the rule that a multi-section work yields a section index unless a section number is supplied.

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?

Front-loaded with the return behavior, then usage, then two compact examples. Every sentence carries information (formatting, section logic, scope limits) with no 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?

With an output schema present, the description needn't restate return fields, and it correctly focuses on behavior an agent can't infer: section-index fallback and content-type marking. Annotations plus schema plus description leave no material gap for correct invocation.

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 baseline is 3; the description still adds value by tying `identifier` formats to concrete, real-looking examples and by showing the combined identifier+section call. It does not add syntax or constraints beyond the schema, so it stops short of a 5.

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?

Opens with a specific verb and resource ("Returns the text of a poem") and immediately scopes it to the ReadingRate collection. It draws a clear boundary against the sibling search/annotation tools by stating it returns only existing collection poems and does not write, continue or translate.

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?

Gives an explicit trigger ("when the user asks to read or see a specific poem, or part of one") and explicit exclusions (no writing, continuing or translating). The section-vs-list behavior is also flagged as a usage condition, so the agent knows when to pass `section`.

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?

Annotations already declare readOnly, idempotent, closed-world and non-destructive, so the safety profile is covered. Beyond that the description adds genuine value by disclosing the aggregation axes and that a computed 'mastery stage' is returned per bucket — a non-obvious derived field. No auth, caching, or scope caveats are mentioned, which keeps it short of a 5.

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 sentences, zero filler. The output shape is front-loaded first and the invocation trigger second, which matches how an agent reads a definition.

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?

With an output schema present and annotations covering safety, the description need not explain return structure, and it is adequate for correct invocation. The one remaining hole is the unresolved boundary with the sibling poetry-stats tool, which could still cause a wrong tool pick.

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 tool takes no parameters, so there is no per-parameter meaning to convey; baseline 4 applies. The description correctly implies a single implicit scope (the current reader) without adding confusing pseudo-parameters.

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 ('shows how widely the reader has read poetry... by poetic form, by era and by poet') and enumerates the returned metrics (distinct poems read, total reads, mastery stage). An agent knows exactly what data this produces. It does not, however, differentiate itself from the close sibling get_poetry_reading_stats, which likely overlaps in subject matter.

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 second sentence gives an explicit trigger: when the reader asks which forms of poetry they have read, or how their poetry reading spreads across eras and poets. That is clear positive guidance, but no exclusion is given against the near-neighbour get_poetry_reading_stats or the broader get_reading_domain, leaving an overlap the agent must guess through.

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?

Annotations already declare readOnly/idempotent/openWorld=false, so safety is covered; the description adds real value by spelling out what the output contains (ranked poems with read counts and last-read dates, breadth-vs-depth judgement). It doesn't explain that half_life_days tunes the recency weighting, which is the one behavioral knob a caller might misjudge.

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?

Front-loaded with the core verb and output inventory, then a distinct trigger sentence and a compact JSON example — every element earns its place. The first sentence runs long with semicolons, but no content is padding.

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?

With a rich output schema and full annotation coverage, the description need not explain return values or safety, and it appropriately focuses on scope and triggers. The only gap is that the recency-weighting parameter, which shapes the ranking it promises, is left to the schema alone.

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%, so both parameters (limit, half_life_days) are already fully documented and the baseline is 3. The description contributes only a small example ({"limit": 10}) and never clarifies half_life_days' effect on ranking, so it adds no meaning 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?

Uses a specific verb and resource ('Summarizes the reader's poetry reading in ReadingRate') and enumerates the concrete outputs: poems ranked by frequency and recency, heart-known line counts, and breadth-vs-depth. It's clearly differentiated in substance from generic siblings like get_reading_stats or get_top_books, though it never names those siblings explicitly to make the boundary unmistakable.

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 'Use when the reader asks...' sentence gives three concrete, quotable trigger scenarios (which poems they return to, how much poetry they read, how many lines they know by heart). It stops short of stating when NOT to use it or naming alternatives such as get_reading_stats for prose or general reading.

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?

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real operational context: history only exists from when logging began, so days before logged_since are unknown rather than unread, and the timezone resolution chain (explicit IANA zone → notification setting → UTC). That is meaningful disclosure beyond the annotations, though it never says what happens if the book_id has no recorded readings.

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?

Front-loaded with what is returned, then when-to-use, then the data-availability caveat, then examples — a sensible ordering with no filler sentences. The third example is arguably redundant with the schema's default note, but the two non-trivial ones earn their space.

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?

With an output schema present, return-value exposition is unnecessary and correctly omitted; the description covers scope, alternatives, timezone resolution, and the log-start data gap. The only loose thread is that `logged_since` is referenced without being defined, and behavior for an out-of-range `reading_number` is unaddressed.

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 already 100%, so the schema documents the three params; the description still adds value by explaining the fallback behavior behind `timezone` and by exemplifying its format. The `reading_number` default (latest) is only stated in the schema, so the description adds no extra there.

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 — per-day page/progress records for a single reading of one book — and enumerates the exact fields returned (furthest page, page left off, pages read, percent). It explicitly routes the reader to get_reading_history for the book-level metadata, so it is unmistakable against siblings like get_reading_stats or get_reading_trajectory.

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?

Gives four concrete trigger questions ('how far they got each day', 'how many pages on which days', 'how long a book took day by day', 'wants a chart of their progress') and names the alternative tool plus the condition that selects it. No inference required.

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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is fully covered and an output schema exists for return values. The description's added value is the domain-id provenance for list_reading_domains and the shape of what's returned, which is mild — it doesn't mention scoping, empty/unstarted domains, or behavior for an invalid id.

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?

Front-loaded with the purpose sentence, then usage, then prerequisite, then a compact example — no wasted prose. The example JSON duplicates information already implied by the schema, a minor 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?

An output schema and rich annotations are present, and the description supplies trigger context and id provenance, so an agent has what it needs to call it correctly. The only remaining gap is routing vs. get_poetic_form_mastery / get_reading_stats for overlapping progress questions.

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% for the single parameter, and the schema text itself already says 'from list_reading_domains', so the description's provenance hint is largely redundant. The inline example call adds only marginal clarity. Baseline 3 is appropriate when the schema does the work.

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 (describes the reader's progress in one reading domain) and enumerates the payload: mastery stage, books, words/hours, quotes, reflections, next-stage requirements. That clearly separates it from list_reading_domains (enumerates domains) and get_reading_stats (aggregate stats). It doesn't explicitly distinguish itself from the adjacent get_poetic_form_mastery, which covers a similar mastery concept, so not a full 5.

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?

Gives an explicit trigger ('when the reader asks about their progress in a particular genre, culture, period or theme, or what it takes to reach the next stage') plus the prerequisite that domain_id comes from list_reading_domains. No when-not guidance or explicit alternative for aggregate stats, so short of 5.

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?

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds real behavior beyond that: what happens when no goal exists (it says so and proposes one from past reading) and that the tool is non-mutating. It does not mention auth or rate limits, but for a local read-only tool those are minor.

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?

Front-loaded with what the tool returns, then the no-goal fallback, then the usage trigger — a sensible ordering with no filler. The enumerated return fields partially duplicate the output schema, which is the only wasted space.

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?

With an output schema present, the description needn't explain return values, and annotations cover the safety profile; the single optional param is fully documented in schema. What remains is that year-scoping behavior (e.g., querying a past year's goal) is never addressed in prose.

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?

Only one parameter and schema coverage is 100%, with the default (current year) documented in the schema itself. The description never mentions the year parameter, so it adds no semantics beyond the schema — 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 (yearly book goal + progress) and enumerates exactly what is reported: books finished, books left, on-track status, required pace, books per month. It also draws a hard boundary — 'It does not set a goal' — which separates it from any goal-mutation tool, and the yearly-goal framing distinguishes it from get_reading_stats and get_reading_trajectory.

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 'Use when...' sentence gives three concrete user phrasings (how am I doing on my goal, am I on track, how many books this year) that map cleanly to invocation. The exclusion 'It does not set a goal' is stated, but no sibling is named as the alternative for adjacent questions like general reading stats or monthly summaries.

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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so safety is covered. The description adds genuinely new behavioral context beyond that: results are ordered by newest activity, status is an optional filter with 'omit for all' semantics, and include_sessions toggles an expansion per book. Pagination cursor behaviour is not mentioned, but limit is schema-documented.

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?

Three short paragraphs: what it returns first, when to call it second, how to shape the response third. No filler words, no restatement of the title, and the most decision-relevant information is front-loaded.

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?

With a full output schema and rich annotations carrying safety, defaults, and closed-world semantics, the description only needs to add ordering, use cases, and filter intent, all of which it does. Nothing an agent needs in order to call this correctly is missing.

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 earns a point by framing status as an optional filter (omit for all) and clarifying that include_sessions expands each book with its logged sessions rather than filtering results. It does not add format or syntax detail beyond the schema, but it clarifies intent, not just restates 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 first sentence names a specific verb (lists) and resource (books in the reader's library) and enumerates the returned fields: status, rating, start/finish dates, reflection, plus ordering (newest activity first). This distinguishes it clearly from get_reading_stats, get_top_books, and get_currently_reading, which summarize rather than enumerate library entries.

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 'Use when' paragraph gives four concrete trigger scenarios (what they've read, want-to-read list, ratings, whether specific books were read), which is strong positive routing. It never names an alternative sibling or a 'when not to use' boundary, so an agent must still infer when to prefer get_currently_reading over this tool.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true and openWorldHint=false, so the safety profile is covered. The description adds value by describing the shape of the result (items 'each with its id'), which is what enables the agent to chain into delete_reading_insight, and by explaining that insight_query searches across books. Pagination/limit defaults are left to the schema, which is acceptable.

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?

Front-loaded with the return content, then usage guidance, then the alternative, then examples — a sensible ordering with little waste. The example block is mildly redundant with the sentence above it, but short enough not to be bloat.

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?

An output schema exists, so return fields need no re-explanation, yet the description still summarizes what is returned and why the ids matter. Combined with the routing guidance and the zero-required-parameter flexibility (both filters optional), an agent has everything needed to call this correctly.

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 earns extra by explaining the semantic difference between the two filters ('Pass book_id for one book's notes, or insight_query to get the saved insights closest to a topic, from any book') and by giving two concrete example payloads. It does not discuss how the two parameters interact if both are supplied, which keeps it from a 5.

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 first sentence names the specific resource (the reader's highlights, notes, generated insights, and saved insights) with their ids, so the agent knows exactly what data is returned. It is clearly distinguishable from search_book_content (searches book text) and delete_reading_insight (deletes one), which are the two closest siblings.

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?

Explicit 'Use when the reader asks what they thought or noted about a book...' clause names the triggering intent, and the closing sentence names the alternative ('To search the text of a book, use search_book_content'). The mention of 'which saved insight to delete' also routes the agent toward the delete flow.

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?

The annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful scope by naming the metrics summarized, but it does not disclose whether the record is all-time or filtered, how fresh the data is, or any behavioral limits beyond what the annotations and output schema likely provide.

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 with no wasted framing. The purpose and metric list come first, and the usage guidance follows immediately, making it well front-loaded for quick agent parsing.

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?

With no parameters, rich annotations, and an output schema, the description is largely complete for invocation. The remaining gap is sibling differentiation: it does not clarify how this differs from poetry reading stats, monthly reading summaries, or reading trajectory tools, which could matter for an agent selecting among similar statistics tools.

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 tool takes no parameters, so there are no parameter semantics to explain. Per the rubric, a zero-parameter tool receives a baseline of 4; the description does not need to compensate for an input schema gap.

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 (summarizes) and resource (the reader's ReadingRate reading record), then enumerates the concrete metrics covered: reading speed, difficulty range, genres/themes, books per month, and rating distribution. It is clear what the tool produces, but it does not explicitly distinguish itself from close siblings such as get_poetry_reading_stats, get_monthly_reading_summary, or get_reading_trajectory.

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 second sentence gives clear contextual triggers: use when the user asks how fast they read, what difficulty suits them, what genres or themes they read most, or how their ratings are spread. It does not name alternatives or state when not to use it, but the usage context is explicit enough for an agent to recognize the intended calls.

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?

The description goes well beyond the annotations by explaining that insights may be generated on demand using the reader's past year of finished books, sent to an AI provider, stored for seven days in place of earlier insights, and counted against AI usage. It also warns that generation takes several seconds and occurs at most once per day, which aligns with the destructiveHint=true and readOnlyHint=false annotations.

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 purpose is front-loaded, followed by operational context and a clear alternative route. The extra detail about generation cost and frequency is valuable rather than redundant, 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?

The description covers purpose, usage conditions, generation behavior, side effects, cost, cadence, and the best sibling alternative. With an output schema present, it does not need to describe return values, and the annotations are reinforced rather than repeated.

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 tool has zero input parameters and an empty schema, so there are no parameter semantics to clarify. The description appropriately focuses on behavior rather than input details.

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 states a specific verb and resource: it returns written insights about how the reader's reading has been changing across genres, authors, pace, and themes. It also distinguishes itself from the closest sibling by saying that numeric pace and genre data belong to get_reading_stats.

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 explicitly says when to use the tool: when the reader asks about reading patterns, trends, or trajectory. It also names the alternative for numeric data, get_reading_stats, giving a clear routing rule.

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?

Annotations already cover the safety profile (readOnly, idempotent, openWorld=false), and the description adds real behavioral context beyond them: that every non-canon list is computed from literary-regard scores rather than readers' votes, that a country or language lacking a list page is still ranked from catalog holdings, that the answer reports how many books the list holds, and that an unknown subject returns the full subject list. These are non-obvious behaviors an agent could not infer from the schema.

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?

Well front-loaded: purpose first, then usage and alternatives, then combination semantics, then examples. The seven examples are somewhat redundant with the 100%-covered schema and push the definition long, but each sentence in the prose section carries information.

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?

An output schema exists, so return values need not be explained, yet the description still notes that each answer gives the list's page address and list size. With zero required parameters, an open filter model, and a documented default (curated canon of 100), an agent has everything needed to call this correctly.

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 per-parameter meaning is already documented in detail (enumerated genres, difficulty bands, which countries/languages have list pages). The description's added value is the combination rule ('Filters combine: {country: Japan, author_gender: female} ranks books by Japanese women') and the fallback for unknown subjects, which the schema does not state. The examples demonstrate valid cross-parameter combinations but repeat values 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?

Opens with a specific verb and resource ('Returns the top of one of the ranked book lists published on readingrate.com') and immediately enumerates the axes (country, language, genre, subject, gender, difficulty) plus the no-filter default of the curated canon of 100. An agent can distinguish this from search_books and get_award_winners without opening any schema.

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?

Explicitly states when to use it ('top, greatest or most important books of a country, a language, a genre, a period or a theme... or for the hardest or easiest great books') and names both alternatives with their selecting conditions ('For books matching a search, use search_books; for prize results, use get_award_winners'). The worked examples reinforce the routing.

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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description contributes scope behavior ('the reader belongs to' — membership-limited, personal view) and previews what each entry carries (role, current book). It doesn't mention empty-state behavior or whether clubs the reader merely follows are included, which keeps it from a 5.

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 sentences: one defines the return, one routes the agent. The core definition is front-loaded and every clause earns its place, with no restatement of the title.

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?

A parameterless read with an output schema, so return structure needn't be spelled out; the description still summarizes the payload (role per club, current book). Combined with full annotation coverage, an agent has everything needed to call it correctly.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the 4 baseline applies. No misleading hints about filtering or pagination are introduced.

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+resource ('Lists the ReadingRate book clubs the reader belongs to') and adds scope details: the reader's role in each and each club's current book. That scope wording alone separates it from get_book_club and get_book_club_current_read without opening a schema.

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?

Explicit trigger ('Use when the reader asks about their book clubs or what their clubs are reading') followed by two named alternatives with the exact condition that selects each. Nothing about routing is left to inference.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds non-obvious behavioral context beyond that: result ordering ('earliest first'), that each item carries a known-lines-by-heart figure, and that grading is a separate mutation via record_quote_review. It does not discuss empty-result behavior or pagination beyond the limit, keeping it short of a 5.

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 tight sentences plus a compact example, with the scoping and ordering facts front-loaded and the follow-up tool named last in workflow order. No sentence is 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 read-only, single-optional-param tool with an output schema and full annotations, the description covers purpose, trigger, ordering, and the next step, so an agent can invoke it correctly. Minor omissions (what an empty due-list looks like, whether limit truncates silently) are low-risk given the output schema.

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?

With 100% schema description coverage and a single optional 'limit' param already documented as default 5 / max 20, the schema does the heavy lifting. The description's only addition is an illustrative call, {"limit": 5}, which adds marginal clarity but no new semantics; baseline 3 is appropriate.

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 ('Lists') and a precisely scoped resource: saved quotes and memorized poem passages that are due for review today in spaced-repetition practice, ordered earliest first, with known-lines counts. The 'due for review today' qualifier cleanly separates it from list_saved_quotes, so an agent can route correctly without opening either schema.

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?

Gives explicit trigger conditions ('reader asks to be quizzed... what is due for review... how many lines they know by heart') and names the follow-up tool, record_quote_review, with the condition that selects it ('after the reader answers'). Both when-to-use and the alternative path are stated, not implied.

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?

Annotations already establish that this is a safe, read-only, idempotent operation, and the description adds useful behavioral scope: up to 50 domains, deepest first. It does not discuss pagination or truncation beyond the 50-item cap, but that is a minor gap for this kind of list tool.

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 front-loaded with the core resource and contents, then follows with usage guidance and alternatives. Every sentence adds distinct information with no repetition 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?

With a full output schema, complete annotations, zero parameters, and clear alternatives, the description supplies everything needed to choose and invoke the tool correctly. Its remaining omissions are minor and not necessary for correct use.

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 tool takes zero parameters, so there is no parameter semantics for the description to explain. The baseline for a parameterless tool is 4, and the description correctly does not invent parameter details.

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: lists the reader's reading domains, including what is reported in each and the ordering. It clearly distinguishes this aggregate list from get_reading_domain and get_poetic_form_mastery.

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?

Explicitly names when to use it: when the reader asks what areas they have read deeply in, know most about, or how domain progress looks. It also names two alternatives and the conditions that select them.

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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's job is to add ordering and scope – which it does with 'newest first' and the two narrowing modes. Defaults and pagination limits are only in the schema, which is an acceptable but minor gap.

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?

Three tight elements: capability, use case, example – front-loaded and waste-free. The example string is slightly redundant with a fully documented schema, but it usefully illustrates combining book_id and search.

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?

With an output schema present, return values needn't be enumerated; the description nonetheless previews page, speaker, notes and themes, which helps the agent decide whether the result answers the user's question. What remains unstated – default limit behavior, whether search is full-text or substring – is minor for a simple read tool.

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 explaining that narrowing can be to one book OR to quotes containing given words, and by supplying a combined example with two parameters. That gives an agent a sense of how filters compose beyond the per-field schema text.

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 ('lists the quotes and passages the reader has saved'), plus ordering ('newest first') and returned fields. It is clear what the tool returns, but it never names or contrasts the closest sibling (list_quotes_due_for_review), leaving that distinction to be inferred.

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?

'Use when the user asks for their saved quotes or highlights, or for what they saved from a particular book' gives a concrete trigger and scope. It stops short of stating exclusions (e.g., that review-queue quotes belong to list_quotes_due_for_review), so it is clear guidance without full routing.

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?

Goes beyond the annotations by naming downstream effects: reads feed get_poetry_reading_stats rankings and daily reading connections. 'Each call adds one more read' reinforces the non-idempotent behavior declared in annotations with a concrete consequence. It stops short of describing failure modes (e.g., unknown identifier) for a mutation, so not a 5.

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?

Front-loaded with the core action, then usage trigger, then behavioral consequence, then compact examples. Every sentence carries information and nothing is redundant.

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 2-parameter mutation with full annotations and an output schema, the definition covers what it does, when to invoke it, side effects, and the section handling rule. Nothing an agent needs to call it correctly is missing.

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 3 is the baseline; the description earns above that by giving worked examples of both the identifier-only and identifier+section call shapes, clarifying the 'poet/poem' anchor format by reference to get_poem.

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?

Specific verb and resource: 'Records that the reader read a poem from the ReadingRate collection, adding one read to its count.' This clearly separates it from log_reading_session (session-level) and save_poem_line (saving a line rather than a read event).

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?

Explicit trigger conditions: 'Use when the reader says they read or reread a poem, or asks to mark one as read,' plus the constraint that multi-section works are logged one section at a time. It does not explicitly name an alternative sibling (e.g., log_reading_session) for contrast, so a 4 rather than 5.

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?

Beyond the annotations, the description discloses concrete state effects: one journal entry per book per day, second call extends that day's pages and appends notes, want-to-read books transition to reading, and front_matter_ends_on is persisted so later arabic pages count after it. It reinforces the non-idempotent annotation with an explicit caution against repeating successful calls.

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?

Front-loaded with purpose, then usage, then parameter rules, then compact JSON examples — a sensible ordering. It is dense but nearly every sentence carries a rule; only minor overlap exists between the prose about setting the current page and the parameter descriptions.

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?

With an output schema present, the description needn't explain return values, and it covers the remaining ground: triggers, prerequisites, mutual exclusivity, roman-numeral edge cases, and duplicate-call risk. Nothing an agent needs to invoke this mutation correctly is missing.

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%, but the description adds rules the schema does not encode: pages_read/current_page/roman_page are mutually exclusive ('only one of them'), a note may be sent alone, and roman numbering for introductions must be recorded via front_matter_ends_on with special '0' semantics that removes those pages. These are real constraints, not restatements.

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?

Specific verb and resource ('Logs reading for a book in the reader's ReadingRate library') plus a precise enumeration of side effects: sets current page, adds pages to today's journal entry, appends note, and moves want-to-read books to reading. This clearly separates it from siblings like update_book_status or save_reading_insight, which do not log session pages.

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?

'Use when the user says how many pages they read, which page they are on, or wants a thought about today's reading saved with it' gives an explicit trigger condition. It also names the prerequisite alternative ('For a book not yet in their library, use add_book_to_library first') and a negative instruction ('do not repeat a call that succeeded').

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?

Beyond the annotations (readOnly/openWorld/idempotent), the description discloses fuzzy-match tolerance for misspellings, the confidence-level taxonomy (exact/high/medium/low), the Open Library fallback for books not in the catalog with an 'unmatched' return shape, and the ~20-book cap with its error behavior. That is real behavioral context an agent cannot get from structured fields.

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?

Front-loaded with the core verb and return shape, then usage, then limits, then an example. Every paragraph serves a distinct purpose and none repeats the schema verbatim.

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?

Output schema exists, so return values needn't be re-explained, yet the description still characterizes the result (analysis + confidence, or unmatched with Open Library data). Input forms, batch limits, and sibling routing are all covered for a one-parameter read tool.

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 with a concrete JSON example showing all three item shapes and the batch size ceiling. It doesn't state whether isbn/title/author may be combined arbitrarily or which form matches best, so it stops short of a 5.

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 ('Matches a list of books to the ReadingRate catalog in one call') and enumerates the accepted input forms (ISBN, title, title+author) plus what each result contains (analysis + confidence level). It also distinguishes itself from the single-book sibling get_book_details by name.

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?

Gives explicit when-to-use conditions ('several books at once', 'photographed bookshelf or a pasted list') and names the alternative for the single-book case. It even pre-empts the failure mode by saying a longer list returns an error stating the limit and should be split.

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?

Annotations declare a non-readonly, non-idempotent, destructive mutation, and the description earns credit by explaining the actual behavior: the previous schedule is replaced and recall quality directly drives how far out the next review moves. It also addresses non-idempotency by stating each call records one review. It does not clarify whether prior review history is lost when the schedule is replaced, which is the main destructive question left open.

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?

It is front-loaded with purpose and behavior before the rubric, and every sentence is load-bearing. The grade enumeration and the JSON example are somewhat redundant with each other and with the schema, which keeps it from a 5.

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 an output schema exists, return values need not be explained. The description still covers the scheduling consequence, the grading scale, the once-per-review constraint, and the sibling dependency, which is everything an agent needs to invoke this correctly.

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 both parameters are already documented, but the description adds real value by spelling out the full 0–5 grade rubric with concrete anchors (0 no memory, 3 right with serious difficulty, 5 perfect) and by giving a literal call example. Only the quote_id sourcing is a restatement of 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 states a specific verb-and-resource pair: it records recall quality for one saved quote/passage on a 0–5 scale and reschedules the next review. It also names the sibling it pairs with (list_quotes_due_for_review), so an agent can place it in the workflow without inspecting the schema.

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 gives a clear trigger condition: use when the reader has answered a review question from list_quotes_due_for_review and has stated or made clear how well they remembered it. It also warns to grade an item once per review. There is no explicit when-not case beyond that, so it stops short of a 5.

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?

Goes beyond the annotations by explaining downstream consequences (saved lines surface alongside other quotes and appear in quote review) and by spelling out the practical meaning of idempotentHint=false: 'Each call saves the line again.' That is exactly the kind of duplicate-accumulation warning an agent needs for a non-idempotent write.

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?

Front-loads what gets saved and where, then usage rules, then a copy-ready example call. Every sentence carries distinct information; nothing is repeated from the schema apart from a harmless field mention.

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?

Annotations cover the safety profile, an output schema exists, and the description supplies the remaining agent-relevant context: where saved lines appear, the review workflow they feed, and the duplicate-save hazard. Nothing needed to call it correctly is missing.

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%, so both parameters and the anchor format are already documented in the schema, including the same example anchor. The description adds only a light restatement ('with an optional note'), 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 ('Saves one line of a poem') plus the destination ('the reader's ReadingRate quotes') and the anchoring constraint. It is clearly separable from sibling writes like save_quote and annotate_poem_line without opening any schema.

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?

Gives an explicit trigger ('Use when the reader asks to save, keep or remember a line of a poem') and names the alternative for the adjacent-but-different intent ('To write a note about a line without saving it as a quote, use annotate_poem_line'). The 'save a line once' rule closes the remaining ambiguity.

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?

The annotations already declare this is a non-readonly, non-idempotent, non-destructive mutation. The description adds useful behavioral context by stating that saved quotes appear in the ReadingRate app and quote review, and that repeated calls create duplicate saves; this reinforces non-idempotency in plain language.

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 front-loaded with the main action and destination, followed by usage guidance, duplicate-save warning, and a compact example. Every sentence contributes practical information without excessive 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?

For a six-parameter mutation tool with full schema coverage, annotations, and an output schema, the description covers the key gaps: what it creates, where it appears, when to use it, the sibling alternative, and duplicate-save behavior.

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 already 100%, so the schema carries most parameter meaning. The description still adds value by summarizing optional fields (page, speaker, notes, themes) and providing a concrete call example with book_id and quote_text.

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 gives a precise verb and resource: saves a passage the reader asks to keep to ReadingRate quotes, under a library book. It also names the sibling save_poem_line for poem lines, so an agent can distinguish this tool from nearby save operations.

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 explicitly states when to use the tool: when the user asks to save, keep, or remember a quote or passage from a book. It also gives a clear exclusion/alternative for poem lines via save_poem_line.

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?

Annotations already declare non-readonly, non-idempotent, non-destructive, and open-world behavior; the description adds substantive side effects the annotations cannot convey — persistence with the books, surfacing in the journal, retrieval via get_reading_notes, and an external copy to Notion. It also states the privacy boundary ('Only the fields below are sent'). The non-idempotent hint is reinforced rather than contradicted.

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?

Front-loads the effect, then the usage rule, then the example — a sensible order with no filler sentences. Slightly dense (three stacked clauses in the opening sentence), but every element adds usable information.

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 mutation tool with rich annotations and an output schema, the description covers trigger conditions, side effects, deduplication, and downstream visibility, leaving nothing an agent needs before calling it. Return-value details are correctly delegated to the output schema.

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%, so the baseline would be 3; the description goes beyond it with a worked example showing how book_ids, summary, key_insights, and topics combine, plus the framing of takeaways 'in the reader's terms'. It does not restate the length limits, which properly remain 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?

States a specific verb+resource ('Saves a reading insight to the reader's ReadingRate account') and enumerates exactly what the insight contains (summary, key takeaways, books, optional topics). It clearly distinguishes itself from adjacent tools by naming get_reading_notes as the retrieval path and delete_reading_insight as the removal path.

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?

Explicit trigger ('Use only when the reader asks to save or keep something from the discussion'), a required confirmation workflow ('Show them the summary and takeaways first and save once they agree'), and a de-duplication rule ('Each call saves a new insight, so save a discussion once'). It also names the alternative for removal.

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?

Annotations already cover safety (readOnlyHint, idempotent, non-destructive), and the description goes well beyond them with substantive behaviors: book text exists only for self-uploaded copies while poems are always searchable, and a detailed spoiler-protection policy keyed to want-to-read / currently-reading / finished status and logged position. Those are exactly the conditions an agent cannot infer from structured fields and that would otherwise cause wrong or empty calls.

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 shape are front-loaded, then eligibility, then spoiler rules, then examples – a sensible escalation. It is longer than most definitions and the spoiler paragraph is dense and partly duplicates the schema, but every section carries actionable information rather than 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?

An output schema exists so return values need no prose, and the description still covers everything else that governs success: id sourcing, per-format eligibility, spoiler gating across reading states, and worked examples for both a book and a poem call. Nothing an agent needs to call it correctly is missing.

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%, so the schema already documents query, book_id, poem_id, limit and spoiler_protection, including the default-with-no-position edge case. The description mostly restates this (the spoiler paragraph mirrors the spoiler_protection schema text) and adds only usage examples, so 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?

Opens with a specific verb and resource ("Searches the text of one book or one poem") and adds the key differentiator, "by meaning rather than exact words." It also states what is returned (passages with page/chapter or line plus neighbours, plus relevance score), so the agent can separate it from search_books and search_poems without reading schemas.

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?

Explicit trigger ("Use when the user asks to find a passage, a scene, or what a book or poem says about something") plus the prerequisite that the book/poem is already identified by id, naming where those ids come from (search_books, get_reading_history, get_currently_reading). It also names the sibling to use instead when there is no topic (get_passages_near_reading_position), covering the when-not case.

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?

Annotations already declare readOnlyHint, idempotentHint, closed-world and non-destructive, so safety is covered; the description adds real behavioral context beyond that — results are presented as cards, difficulty is a 0-100 composite of nine prose/meaning dimensions, and results carry no indication of whether the user has read the book. It stops short of describing ordering, empty-result behavior, or what happens when limit exceeds the catalog, leaving minor gaps.

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?

Front-loaded with purpose, then usage routing, then returns, then examples — a clean progression with no filler sentences. The explicit 'Returns:' enumeration is partly redundant given an output schema exists, which keeps it off a 5.

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 7-parameter, zero-required search tool with an output schema, the description supplies everything needed to call it correctly, including the read-history caveat that prevents a wrong inference from results. The only room left is behavioral detail on ordering and pagination past the 50-item cap.

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, but the four worked examples demonstrate how parameters combine (query + genres + a difficulty band, and genre-only with difficulty_max), which the schema cannot express. The Russian example also clarifies the cross-cutting rule that localized fields are added while difficulty scores stay language-independent, going beyond the schema's note about Cyrillic auto-detection.

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 (searches) plus the resource (ReadingRate book catalog) and enumerates the searchable facets (title, author, genre, theme, difficulty). It also names the concrete output shape (book cards with a 0-100 difficulty score built from nine dimensions), so an agent can distinguish it from content search, award lookups, and batch lookups without opening a schema.

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?

Gives an explicit when-to-use clause ('asks to find books by an author, on a subject, in a genre, or within a difficulty range') and then routes four alternatives by condition: get_book_details for one book's analysis, get_award_winners for prizes, lookup_books_batch for pasted lists or photographed shelves, get_reading_history for read status. This is the full when/when-not/alternatives pattern.

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?

Annotations already cover read-only/idempotent/closed-world, and the description adds real behavioral context on top: word-level (not semantic) matching, the consequence that paraphrases fail, that only in-collection poems are returned, and a cross-language policy for non-English readers. The anchor-return contract with three sibling tools is exactly the kind of cross-tool behavior annotations cannot express.

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?

Front-loaded with purpose and return shape, then usage, then matching semantics, then a copyable example — a sound ordering with no filler. The cross-language sentence is the longest in the block and is the one an agent is least likely to need on every call, so it is slightly over-weighted for the 10% dimension.

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?

An output schema exists, so return values needn't be explained, and the hard parts (matching mode, collection scope, language policy) are covered. It says nothing about result ordering, how the surrounding lines are bounded, or how limit interacts with truncation, which are the remaining unknowns for a search tool.

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, but the description adds genuine meaning for the required query parameter ("It matches words, so a remembered phrase works better than a paraphrase") and clarifies what an anchor is and who consumes it. limit and poem_id are left entirely to their schema text.

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?

Specific verb+resource ("Searches the words of every poem in the ReadingRate collection") with the result shape named (matching lines, surrounding lines, anchor). The scope word "poem" plus the note that the returned anchor feeds get_poem/save_poem_line/annotate_poem_line lets an agent separate it from prose-oriented siblings like search_book_content or search_books without opening a schema.

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?

Gives a concrete trigger ("when the user half-remembers a line, or wants poems that mention an image or a subject") with a worked example, and draws a clear negative boundary ("does not write, continue or translate poems"). It stops short of naming the sibling an agent should pick instead for prose or for fetching a known poem, so it lands at 4 rather than 5.

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?

Goes beyond the annotations by explaining what the destructiveHint actually means in practice: the summary is persisted to the reader's account and "replaces any summary saved earlier for the same dates," which also explains why the call is idempotent. The one-year date-span limit adds a constraint no structured field conveys.

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?

Front-loaded with the action and data produced, then routing guidance, then a compact example. No sentence is redundant — even the side note about replacement semantics carries behavioral weight.

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?

An output schema exists, so return shape needn't be described; the description covers scope, persistence side effects, date constraints, and the sibling alternative. Everything an agent needs to select and invoke this correctly is present.

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 earns above it by restating the year-apart constraint in prose and providing a concrete worked example with all three parameters, including a period_label pattern the schema only gestures at with a max length.

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 ("Builds a summary of the reader's reading between two dates") and enumerates the content covered: books finished, time/pages read, difficulty, highlights. It is immediately distinguishable from get_monthly_reading_summary by the arbitrary-date-range scope.

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?

Explicitly says when to use it ("a review of a period that is not one calendar month, such as a year in review or a season") and names the alternative for the excluded case: "For a single calendar month, use get_monthly_reading_summary." Both routing directions are covered.

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?

Despite annotations already flagging destructiveHint=true and idempotentHint=true, the description adds real substance: what gets replaced (current status, and for 'read' the rating and finish date), that 'want_to_read' clears the finish date, and the activity-feed/profile-visibility consequences of marking a book read. It doesn't state auth requirements, but for a mutation with full annotation coverage this is well above the bar.

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?

Structure is strong: purpose and per-status effects first, then usage triggers and the alternative, then examples. The profile-visibility paragraph is dense and runs long relative to its weight, which trims a point, but nothing is truly redundant.

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 destructive mutation with an output schema present, the description covers what changes, what is overwritten, conditional parameter behavior, downstream visibility effects, and routing to the sibling tool. An agent could call this correctly without further information.

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 baseline is 3; the description earns above that by explaining the conditional semantics the schema only hints at – 'reading' sets a start date if none exists, 'read' sets finish date plus optional rating, 'want_to_read' clears the finish date. It doesn't clarify the book_id dual-id nuance beyond the schema, keeping it from a 5.

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 (moves) and resource (a book already in the reader's library), enumerates all four target statuses, and spells out the per-status side effects (start date, finish date, clearing finish date). It is unambiguously separable from add_book_to_library, which is named explicitly for the out-of-library case.

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 second paragraph gives concrete trigger phrases (started, finished, stopped, gave up, wants to rate, back on want-to-read) and names the alternative tool plus the condition that selects it (book not yet in library). Both the when-to-use and the when-not-to-use cases are covered.

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