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 real value beyond them: it scopes the blast radius ('Only that entry is removed; the book, its status, and other entries are unaffected'), flags irreversibility ('Cannot be undone'), and specifies the return shape. This is exactly the extra context a destructive tool needs.

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, front-loaded with the action and scope, then the blast-radius constraint, then the return value. Every sentence earns its place 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 no output schema, the description supplies the return value ({deleted: true, id}), and the irreversibility and scoping statements fully cover what an agent must know before invoking an irreversible delete.

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% with a single documented id parameter, so the baseline is 3. The description goes beyond the schema by identifying the provenance of the id (get_reading_journal), which meaningfully helps the agent supply a valid value.

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: 'Permanently delete one of your reading journal entries by id'. It also names get_reading_journal as the source of the id, separating it cleanly from sibling delete tools (delete_list, delete_user_book).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells the agent where to obtain the id ('from get_reading_journal'), which routes usage correctly. It lacks explicit when-not-to-use guidance or named alternatives for the adjacent set_journal_entry, but the context is clear.

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, so the safety profile is known; the description goes further by clarifying blast radius ('the books themselves stay in your library; only the list and its entries are removed') and irreversibility ('Cannot be undone'), which annotations cannot express. It also discloses the return payload.

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?

Four short sentences, each earning its place: action, blast radius, reversibility, return shape, and sibling routing. The destructive action is front-loaded in the first clause.

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

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

For a single-parameter destructive tool with no output schema, the description covers what is destroyed, what survives, irreversibility, the return shape, and the alternative tool. Nothing an agent needs to invoke 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% with a single documented 'id' parameter, so the schema already carries the semantics; baseline 3 applies. The description adds only the ownership constraint ('you own'), with no format or ID-source detail beyond what the schema provides.

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

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

States a specific verb and resource ('Permanently delete a list') plus the ownership scope ('you own'), which distinguishes it from sibling delete tools like delete_user_book and delete_journal_entry. An agent can identify the operation 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?

It routes the adjacent case explicitly: 'To take a single book off use set_list_book with on_list=false,' naming the alternative and its parameter. It does not spell out prerequisites (e.g. ownership checks) or when deletion is inappropriate, but the key sibling disambiguation is present.

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 non-readOnly, but the description adds that the action is irreversible and, importantly, that books and reading progress are unaffected — a side-effect scope that annotations cannot express. It also discloses the return shape.

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, each earning its place: what it does, the alternative, and the collateral-effect clarification plus return value. Front-loaded with the verb and permanence caveat.

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?

No output schema exists, yet the description states the return value ({deleted: true, id}), and it covers irreversibility, alternatives, and unaffected resources. Nothing needed to invoke it safely 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 id parameter is already documented, but the description adds that the id comes from get_reading_goal, which helps the agent source the value correctly. Minor value 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 (delete) and resource (reading goal) plus scope (by id) and permanence. It is clearly distinguishable from siblings like set_reading_goal and delete_user_book.

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 routes the agent: use set_reading_goal(id, archived=true) to hide instead of delete, and names get_reading_goal as the source of the id. Both the when and the when-not are stated.

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 flag destructiveHint=true and idempotentHint=true, but the description adds material context beyond them: the cascade of destroyed data (status, rating, review, private notes), irreversibility ('Cannot be undone'), and the literal return payload. With no output schema, disclosing the return shape is genuinely valuable.

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 dense sentences: what it does, what it destroys, the return value, then the two alternatives. Front-loaded with the destructive action and every clause carries new 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 destructive delete with no output schema, the description covers scope, side effects, irreversibility, return shape, and sibling routing. An agent has everything needed to call it correctly and to prefer alternatives where appropriate.

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 ('Hardcover book ID (will look up your library entry)' / 'Directly specify user_book ID if known'). The description's 'by book_id or user_book_id' adds the either/or framing but no format or lookup 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 ('delete/remove') and resource ('book from your library'), plus the two addressing modes (book_id or user_book_id). It explicitly separates itself from set_user_book and set_list_book, so an agent can pick it without opening another 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 when-not guidance with named alternatives: use set_user_book to change status, set_list_book(on_list=false) to remove from a custom list. Nothing about tool selection 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 flag destructiveHint=true and readOnlyHint=false, but the description adds genuinely new context: exactly what is destroyed ('only that read is removed' while the book, status, rating, and review survive), that it is irreversible, and the return payload. That scoping detail is not derivable from the 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?

Four tight sentences, front-loaded with the action and scope, followed by consequences, return shape, and the sibling alternative. No filler and nothing repeated from 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 single-parameter destructive tool with no output schema, the description covers the action, blast radius, reversibility, return value, and the alternative tool. Nothing an agent needs to invoke 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% with one documented parameter, so the baseline is 3. The description adds provenance value by specifying the id is a user_book_read id obtained from get_user_book, which the schema's terse 'The user_book_read ID to delete' does not establish.

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 precise verb and resource ('Permanently delete one read entry'), defines the granularity (a single start/finish/progress record), and names the sibling it is not ('To remove the whole book use delete_user_book'). An agent can distinguish this from delete_user_book 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?

Explicitly routes the agent: use this for a single read record, use delete_user_book to remove the whole book. It also tells where the id comes from ('from get_user_book'), giving the agent a prerequisite source rather than leaving it to infer.

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 and openWorldHint=true, so the bar is lower, yet the description still adds ordering (newest first), default-scope behavior including the empty-feed case, and the shape of the return object. It repeats 'Read-only' from the annotations rather than adding to it, keeping 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?

Front-loaded with purpose, then scope, then return shape, then sibling disambiguation — good ordering with little waste. The return-shape sentence is justified only because there is no output schema; otherwise it is slightly dense at four sentences.

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 safety and the schema covers all four parameters, so the description only needs to add scope and behavior — which it does, including the empty-feed edge case and response keys. Nothing an agent needs in order to invoke it correctly is missing, though rate limits or ordering guarantees for large offsets go unmentioned.

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 meaning the schema doesn't: the semantic distinction that omitting user_id/username yields the followed-users feed and passing either targets a single user. limit/offset are left to the schema, which documents them adequately.

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 ('Get recent social activity events') and enumerates the event types (status changes, ratings, reviews, list updates). It also names the sibling tools it is not (get_reading_journal, get_user_library(has_review=true)), making the boundary clear 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 the default scope (feed of followed users, empty if you follow nobody) and the condition to override it (pass user_id or username for one user's activity). It also routes to better-fitting alternatives for notes/quotes/progress and review texts, so when-not-to-use is 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?

Annotations already declare readOnlyHint and openWorldHint, and the description redundantly confirms read-only. It adds genuinely new behavioral context: the name-resolution ambiguity, and the shape of the response payload since no output schema exists. It does not cover error cases when no identifier matches.

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 sentences, front-loaded with purpose and lookup keys, then return shape, then the alternative. No filler and every sentence 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?

With no output schema, the description compensates by enumerating the returned fields (bio, birth/death year, counts, book list with title/year/rating). Combined with the annotation safety profile, 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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: at-least-one identifier requirement, the top-match resolution semantics for name, and that books_limit caps the embedded book list. The other params add no extra syntax detail.

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

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

States a specific verb and resource (get an author) plus the three accepted lookups (id, slug, name). It clearly differentiates itself from the sibling search_books, which is named as the multi-candidate alternative.

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 the constraint 'provide at least one' identifier, explains the disambiguation behavior of a name lookup ('resolves to the top search match'), and routes the agent to search_books(query_type='Author') when comparing several candidates. Both the when-to-use and the alternative are named.

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 and openWorldHint, so safety is covered. The description adds real beyond-annotation behavior: the spoiler/only_mentioned flags with a handling instruction ('don't reveal spoiler characters unless asked') and editions returned 'most-read first' up to editions_limit. It restates 'Read-only' redundantly, but the spoiler semantics are genuinely additive.

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?

Dense but front-loaded: the core work-vs-edition distinction leads, followed by the toggle behaviors and routing advice. Every sentence carries information, though the single-block paragraph is slightly heavy to scan for an 8-parameter tool.

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 output schema, the description compensates fully by enumerating the fields returned for both the work and the edition, plus the shapes of the include_characters and include_editions arrays. 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 goes beyond it by explaining the semantic role of each input group (work-level id/slug vs edition-level isbn/asin/edition_id) and what the include_* toggles inject (characters in book order, editions most-read first). This adds meaning the schema descriptions alone don't convey.

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 ('look up') and resource ('a book or one specific edition of it'), then draws the exact work-vs-edition distinction that defines the tool. It explicitly separates itself from siblings (search_books, get_user_book), so an agent can route 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?

Provides explicit selection rules: id or slug yields the work, exactly one of isbn_13/asin/edition_id yields the edition. It also names alternatives and their triggers ('Use search_books first if you only have a title; for your own status/rating... use get_user_book') and points edition ids to set_user_book.

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 only say readOnly/openWorld; the description goes much further by disclosing default sort order (most recently updated first), the pagination scheme in each mode, and that list contents come back in list order with a books array. It also clarifies cross-user readability, which the annotations do not.

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 mode split, then per-mode return shape and pagination, then the sibling pointer. Three dense clauses, no repetition, every phrase 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?

There is no output schema, so the description must carry the return contract, and it does: it enumerates the top-level envelope {total, returned, offset, lists}, the per-list fields, and the nested books fields. An agent has everything needed to call it and interpret the response.

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 each parameter description already states 'Without id' / 'With id' scope plus defaults and maxima. The description restates that same mode-to-parameter mapping and adds no syntax or format detail beyond it, so it sits at the baseline.

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 and splits the tool into its two modes (list your own lists vs. fetch a single list) with the exact return shape for each. That dual-mode framing lets an agent distinguish it from siblings like search_books or get_user_library 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 conditions usage: omit id to enumerate your own lists, supply id to fetch one list (yours or another user's). It also names the alternative for discovering other users' lists, search_books(query_type='List'), which is the exact routing decision an agent needs.

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, so the brief 'Read-only' line is largely redundant, but the description adds genuinely new behavior: default ordering by answer count, pagination via limit/offset, the shape of the returned object, and the featured filter semantics. It does not mention result caps or failure modes, but for a simple read tool this is close to sufficient.

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 purpose and ordering, then routing, then return shape, then next step – a sensible information hierarchy with no filler. The 'Read-only' sentence is the only line that does not earn its place given the annotation, keeping 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?

No output schema exists, but the description enumerates the return envelope ({returned, offset, prompts}) and key fields (id, question, description, answers_count, books_count), which is exactly what the agent needs. Combined with the sibling routing and the set_prompt_answer handoff, nothing material is missing for a 3-param 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% and all three parameters (limit, offset, featured) are already documented in the schema, so the description's restatement of featured and pagination adds no syntax or constraint information beyond it. Baseline 3 applies when the schema does the heavy lifting.

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 (list community book prompts) with a concrete example of what a prompt is, plus the default ordering (most answered first). It is clearly distinguishable from search_books, which it explicitly names as the retrieval-by-keyword alternative.

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 split: browse here vs. search_books(query_type='Prompt') to find by words in the question. It also chains forward by naming set_prompt_answer as the consumer of a prompt id, so the agent knows the follow-up action.

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, and the description adds the non-obvious resolution behavior (name → top search match) plus what the response includes. It stops short of stating failure behavior when nothing resolves or when multiple identifiers are supplied, which matters for an openWorld lookup.

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?

One tight passage with the lookup constraint front-loaded and the return shape trailing; every clause (identifier exclusivity, name resolution, editions paging) carries information the schema and annotations do not.

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 output schema, the description usefully names the returned fields, including the embedded book stubs and paging controls, so return values are covered. Remaining gap is edge-case behavior: no-result, ambiguous name, or multiple identifiers passed.

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, and the description exceeds it by explaining that exactly one identifier should be supplied, how name matching resolves, and that editions_limit/editions_offset page the embedded editions list.

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 (look up) and resource (publisher), enumerates the three accepted identifier forms, and clarifies that a name resolves to the top match. An agent can distinguish this from get_book/get_author immediately.

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 parenthetical "provide one" states the selection constraint across id/slug/name, which is real usage guidance given zero required parameters. It does not name an alternative tool or say when to prefer this over search_books, so it falls short of full when/when-not 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 and openWorldHint, so safety is covered; the description reinforces 'Read-only' and adds genuine behavioral context: the return shape ({returned, offset, goals}), per-goal fields, ordering, and that 'goals' is empty when none exist. It stops short of discussing pagination behavior beyond the shape, but that is 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 the core purpose and scope, followed by return shape and then sibling routing — no filler sentences. Every clause (scope, ordering, return fields, empty case, alternatives) carries information 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?

There is no output schema, but the description compensates by enumerating the return structure and the fields of each goal. Combined with the two fully-documented parameters and the readOnly annotation, an agent has everything needed to call and interpret the result.

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 both parameters (limit, offset) are fully documented in the schema, so the description need not compensate. It only implies pagination via the returned/offset fields in the response shape, adding no syntax or default details 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 ('Get ... reading goals') plus a clear scope constraint ('active (non-archived)') and an ordering rule ('soonest end date first'). It also names the sibling tools that handle the other operations (set_reading_goal, delete_reading_goal), so an agent can distinguish it without inspecting 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?

Explicitly routes the agent: use set_reading_goal to create/change/archive and delete_reading_goal to delete. The condition selecting this tool (read the current active goals) is unambiguous, and the empty-result case is disclosed.

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 and openWorldHint, and the description reinforces read-only while adding ordering ('newest first') and a full return shape. It does not mention pagination edge behavior or rate limits, but with annotation coverage the remaining gap is 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?

Three tight sentences: description of contents first, mechanics second, disambiguation last. Slightly dense (return-shape detail inline), but every clause 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?

There is no output schema, and the description compensates by specifying the returned envelope {returned, offset, entries} and per-entry fields, plus ordering and filter combinations. An agent has everything needed to call and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all four parameters are already documented with examples and defaults. The description only restates that book_id and event can be combined and that limit/offset paginate, adding no syntax or format beyond the schema — baseline 3.

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

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

States a specific verb and resource ('Get your own reading journal') and enumerates the event content it contains (notes, quotes, status changes, ratings, reviews, progress). It explicitly distinguishes itself from get_activity_feed and get_user_library(has_review=true), so an agent can route 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?

Names two alternatives with the exact condition that selects each: social feed → get_activity_feed, review texts → get_user_library(has_review=true). It also states the filtering/pagination mechanics, leaving nothing to inference about when to use 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 and openWorldHint=true, so 'Read-only' adds nothing. The description does add real behavioral context beyond them: name resolution silently picks the top search match, and the response is described as series info plus the full ordered book list. It stops short of noting any limits on how many books are returned.

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?

Four short sentences, front-loaded with the identifier options, then return payload, then the sibling escape hatch. No filler and nothing repeated from 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?

No output schema exists, so the description carries the return contract, and it does: series metadata fields plus per-book position, title, release year, and rating in reading order. Combined with the identifier guidance, 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 each parameter is already documented, and the baseline would be 3. The description earns more by supplying the one-of relationship ('provide one') that the schema cannot express, since no parameter is marked required, and by flagging the fuzzy-match semantics of 'name'.

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 plus resource ('Get a book series') with the three accepted identifiers named, and it enumerates what comes back (series info plus books in reading order). An agent can distinguish it from get_book, get_author, and search_books 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?

States the selection constraint ('provide one') and names the alternative explicitly: use search_books(query_type='Series') if a name might be ambiguous. It also warns that a name resolves to the top search match, which tells the agent when this tool's shortcut is unsafe.

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 and openWorldHint, so the 'Read-only' restatement adds little. However, the description adds real behavioral context beyond the annotations: ranking order (most popular first), pagination via limit/offset, and the exact return envelope and fields, which lets an agent plan consumption of results.

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, all front-loaded: purpose, semantics, then disambiguation. No filler, and the sibling routing comes last where it belongs.

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?

No output schema exists, and the description compensates by naming the return shape ({returned, offset, books}) and key book fields. Combined with 100% parameter coverage and annotations, an agent has everything needed to call and consume the result.

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 each parameter is documented with defaults and bounds, so the schema carries the semantics. The description mentions 'duration' default 'week' and limit/offset pagination, which largely repeats the schema rather than adding new meaning (e.g., ordering interplay with offset, or how duration buckets are computed). 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 ('books trending on Hardcover'), plus scope details (time window, popularity ranking, pagination). Explicitly distinguishes itself from get_vibes and search_books, so an agent can route 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 explicit alternatives with the condition that selects each: 'For curated themed collections use get_vibes; for a custom query use search_books with sort=users_count:desc.' That is exactly the when-to-use-this-vs-alternatives guidance the dimension rewards.

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 only declare readOnlyHint/openWorldHint; the description adds substantive traits beyond that: private users' libraries return empty unless followed, stats are restricted to your own profile, follow lists are newest-first, name lookups resolve to the top match, and the call fails on a missing/invalid token. These are real behavioral constraints an agent could not infer from the 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?

Front-loaded with the core behavior, then optional sections, then sibling routing, so it reads in priority order. It is a single dense paragraph with heavy parentheticals that could be broken into bullets, but 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 an 11-parameter, no-output-schema tool, the description covers return contents (bio, book/follower counts, privacy), each optional section's payload, ordering, and failure conditions. An agent has everything needed to call it correctly and interpret the result.

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, but the description adds semantics the schema lacks: include_library explains what each entry contains (community rating vs user_rating) and the privacy caveat, include_stats is scoped to own profile only, and stats_year defaults to the current year. It leaves the limit parameters (follow_limit, library_limit) to 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 ('Get a Hardcover user's profile') plus the scope rule (no args = token owner, otherwise by id/username/name). It explicitly names the adjacent tools it is not (get_activity_feed, set_following), so an agent can distinguish it from siblings 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 explicit routing: default to self with no arguments, look up others by id/username/name, and 'For activity use get_activity_feed; to follow someone use set_following.' Both when-to-use and when-to-use-something-else are stated.

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 readOnlyHint annotation, the description enumerates the return payload (user_book_id, status, ratings, review, private notes, edition, read entries, lists), and discloses exact error strings ('Book not in your library', 'No book found with slug …') plus the caveat that Owned is excluded from the returned lists. This is rich context an agent cannot get from annotations or 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?

Front-loads the core operation and parameter precedence before diving into return fields, and each clause carries information (return shape, error messages, sibling routing). It is a dense single paragraph rather than a tightly segmented one, which slightly hurts scanability but wastes little.

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 output schema, the description compensates fully by describing the returned fields and their downstream use (read-entry ids needed by set_user_book_read/delete_user_book_read). Nothing an agent needs to invoke or interpret the result 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 already 100%, so the baseline is 3; the description adds genuine value by stating the precedence rule 'book_id wins if both are given', resolving an ambiguity the schema does not address. It does not restate slug/ID formats, but the schema handles that.

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 ('Get your own library entry for one book') and immediately distinguishes this from the sibling tools get_book and get_user_library by naming their distinct scopes. An agent can tell exactly which tool handles 'my relationship to this book' versus the book record itself.

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 routes to alternatives: 'for the book itself ... use get_book, and to browse many of your books use get_user_library', and notes list changes go through set_list_book rather than here. This gives concrete when-to-use-this vs when-to-use-another 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 readOnlyHint annotation, it discloses that the operation is read-only, what fields are returned, how date-range results are ordered ('always newest finish first'), and a subtle ownership caveat ('owned books that aren't in your library are not listed'). It also explains filter combination behavior, which is valuable operational context.

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 the core purpose and then proceeds through filters, sorting, return fields, examples, and the sibling alternative. Despite covering nine parameters, every sentence adds useful information; there is 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 nine optional parameters, no output schema, and open-world behavior, the description supplies the return-field list, filter interaction rules, sorting defaults, and edge cases. An agent has enough information to call the tool correctly without needing 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?

Although schema coverage is 100%, the description adds meaningful semantics beyond the schema: it explains how sort interacts with has_review, that date ranges cannot take sort/order, that filters combine, and gives example values such as sort='rating'. This materially helps an agent choose parameters correctly.

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 ('List books in your own library') and defines scope ('any status'), pagination, filtering, sorting, and returned fields. It also explicitly distinguishes itself from the sibling tool get_user_book for a single book's full entry.

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 concrete when-to-use examples: sort='rating' for top-rated books, a date range for 'what did I read in May?', and owned=true combined with status filters. It also names the alternative tool to use for one book's full entry and explains constraints such as date ranges not accepting sort/order.

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 readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful behavioral context: featured filtering is on by default, pagination uses limit/offset, and the result shape includes vibes with nested book data. It does not cover auth or rate limits, so it falls 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?

The description is compact and front-loaded: purpose first, then read-only status, filtering/pagination, return shape, and alternatives. Every sentence carries useful information without 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?

Although there is no output schema, the description explains the return object and the fields included per vibe. Combined with full schema coverage and safety annotations, it gives the agent enough to call the tool 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 four parameters are already documented with defaults and limits. The description reinforces featured filtering and pagination, but it mostly restates what the schema provides rather than adding new parameter 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?

The description gives a specific verb and resource: 'List Hardcover vibes'. It immediately defines vibes as curated, themed book recommendation collections and includes an example, so the agent can distinguish this from sibling list-related tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use alternatives: get_trending_books for popularity rankings and get_list for user-made lists. It also explains the featured-vibes default and pagination behavior, leaving little ambiguity about scope.

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 readOnlyHint and openWorldHint, and the description's 'Read-only' only restates them. However it adds real behavioral context beyond annotations: the default relevance ranking, the effect of supplying 'sort', paging behavior via {total, returned, page}, and the compact hit shape per entity type. It stops short of describing rate limits or errors, so a 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?

A single dense paragraph with the core purpose front-loaded, followed by entity-type scope, return shape, and a routing rule. Every sentence carries distinct information and nothing is 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?

No output schema exists, and the description compensates by specifying the return envelope ({total, returned, page, <type>}) and the per-hit fields. For a 6-parameter read-only search tool, an agent has everything needed to call it and interpret results.

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 is 3. The description adds meaning on top: it explains that query_type selects alternate entity types rather than books, and that results are relevance-ranked unless 'sort' is provided. It doesn't clarify filter_by/per_page interactions, so not 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 ('full-text search') and resource ('Hardcover's catalog'), plus the searchable fields (title, author, ISBN, keyword) and the query_type expansion to other entities. It is clearly distinguishable from the get_* siblings 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?

Explicitly says to use it to discover ids and then call get_book/get_author/etc., and gives a concrete exclusion: if you already have an id, slug, or ISBN, call the matching get_* tool directly. This is textbook when/when-not/alternative 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 idempotency, destructiveness, and open-world behavior; the description adds concrete meaning beyond them: what 'idempotent' means here ('nothing changes'), that an unknown user is an error, and exactly which fields are returned. This is a meaningful behavioral supplement rather than a restatement.

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?

A single dense paragraph that front-loads the core action, then identifier resolution, idempotency, downstream effect, and return shape. Every sentence carries actionable information 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?

No output schema exists, and the description compensates by naming the returned fields (user_id, following, changed) and the error condition for an unknown user. For a three-parameter mutation tool this is fully sufficient.

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 the non-obvious precedence rule that user_id wins when both identifiers are supplied. The boolean semantics are already in the schema, so it falls short of a full 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 description states a specific verb pair (follow/unfollow) and resource (another Hardcover user), with the boolean flag semantics spelled out. No sibling tool does this, so it is unambiguous against the provided tool list.

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 how to trigger each mode via following=true/false, how to identify the target (user_id or username, user_id wins), and points to get_activity_feed as the downstream consumer. An agent has everything needed to choose and call it correctly.

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 the default visibility of new entries (public), that each create produces a separate entry (consistent with idempotentHint=false), and the immutability of book_id on edit — real behavioral context. It does not explicitly warn that editing replaces the existing entry text, which is the main destructive risk flagged by destructiveHint=true.

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 create/edit fork and very dense with useful content; the parenthetical clauses carry the conditional rules efficiently. It is slightly cramped — two distinct modes packed into one sentence — but 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 6-parameter mutation tool with no output schema, everything an agent needs is present: mode selection, conditional required fields, defaults, what cannot be changed, sibling routing for excluded entry types, and the return value (the entry with its id).

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 would be 3, but the description adds meaning the schema cannot express: the schema marks zero required parameters, while the description states book_id, entry, and event are required when creating. It also ties id to get_reading_journal and notes privacy's default.

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 pair (add vs. edit) and the exact resource (a reading journal note/quote), and it explicitly carves out the entry types it does not handle by pointing at set_user_book and set_user_book_read. An agent can distinguish this from get_reading_journal or delete_journal_entry 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?

Mode selection is spelled out precisely: omit id to create, pass an id obtained from get_reading_journal to edit. It also states an exclusion (status/rating/progress entries belong to set_user_book and set_user_book_read) and a behavioral rule for updates (only the fields you pass change, the book can't).

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, idempotentHint=false and openWorldHint=true. Still missing is any disclosure of permission/auth requirements or what happens to fields you omit; a 3 is warranted since the annotation set already carries part of the load and the remaining gaps are real.

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?

Every sentence earns its place: mode selection is front-loaded, then the duplicate-write warning, then the return shape, then the sibling boundary. No filler and 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?

No output schema, and the description compensates by naming the returned fields (id, name, slug, description, privacy). For a 4-param mutation with good schema coverage, nothing an agent needs to call it correctly is absent.

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 documents every parameter including the privacy enum values and the create default. The description mirrors the schema's own mode rules but adds no syntax or format detail beyond what structured fields already provide, 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?

States precise verbs and resource: create a list or change name/description/privacy of an owned list. It also explicitly names the boundary against set_list_book ('Does not change which books are on it') and against get_list, so an agent can separate 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 explicit mode-selection rules (omit id + name to create; pass id plus at least one field to update) and an explicit prerequisite ('check get_list first' because creating twice makes two lists). It also names the alternative tool for book membership, which is a clear when-not-to-use signal.

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 spelling out partial-failure semantics: with list_ids, a list that isn't yours or fails returns an 'error' while the others still change. It also pins down idempotency concretely (already-in-state lists don't change, existing positions are not moved) and enumerates return fields for both modes, which annotations alone cannot convey.

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?

One dense paragraph that front-loads the core action and mode switch, then layers idempotency, side-effect exclusions, return shape, and ID discovery. Nearly every clause carries information an agent needs; nothing is repeated from the name or 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?

With no output schema, the description supplies the return fields for both single and bulk modes and describes the per-list error envelope. Combined with the destructive and idempotent annotations, an agent has everything needed to invoke this correctly and to interpret the response.

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 still adds mode-level meaning by framing list_id as the single-list path (with optional position) and list_ids as the bulk path capped at 20. It does not add format or range detail beyond what the schema already documents, so it sits just above baseline.

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?

Opening clause states a specific verb pair and resource ('Put a book on your lists... or take it off') with the boolean that selects each mode. It explicitly separates itself from set_user_book (library/reading status) and from set_list, so an agent can route correctly 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 explicit mode selection via on_list, an either/or between list_id and list_ids with a stated cap, and redirects to set_user_book when the user actually wants library/reading status changes. It also names the discovery tools (get_list, get_user_book, search_books) for the IDs the caller must supply.

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 write/idempotent/destructive/open-world, but the description adds semantics beyond them: idempotency means the existing description is preserved, not overwritten, and there is a propagation delay of a few seconds before changes appear. It also enumerates the returned fields in the absence of an output 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?

The core operation is front-loaded in sentence one, then idempotency, timing, cardinality, and return fields follow in order of usefulness. Four sentences, no filler, no repetition 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?

For a 4-parameter mutation tool with no output schema, the description covers the mode switch, idempotency, latency, cardinality, return payload, and how to source the two ids. Nothing an agent needs to invoke 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 the baseline is 3, but the description goes slightly further by explaining the behavioral meaning of answered (submit vs withdraw) and by tying description to the add path only ('optionally with a description of why it fits'). It does not add format or constraint 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 pair — answer/withdraw a book on a community prompt — and names the two modes (answered=true/false) in the first sentence. It is clearly distinguishable from read-oriented siblings like get_prompts and search_books, which it references rather than duplicates.

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 explains the when: true to submit, false to withdraw, optional description only when adding. It also gives the when-not ('don't repeat a call immediately') and the alternatives for obtaining inputs (get_prompts for prompt ids, search_books for book ids), plus the allowance to attach several books to one prompt.

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 adds substantial behavior beyond annotations: it explains the upsert rule for matching metric and dates, that only passed fields change, that archive hides from get_reading_goal and is reversible, that permanent deletion is handled elsewhere, and what fields the response contains. This is far richer than the destructive/idempotent hints alone.

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 purpose, then proceeds through create-vs-edit branches, archive behavior, return shape, and the permanent-deletion alternative. Every sentence carries operational information and there is 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?

For a mutation tool with no output schema, the description covers creation, editing, archiving, restoration, conditional required fields, return fields, and the correct sibling for permanent deletion. It is complete enough for an agent to choose and invoke the tool 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?

Although the schema already documents each parameter at 100% coverage, the description adds conditional semantics the schema does not capture: goal, metric, start_date, and end_date are required when creating without an id, and with an id only passed fields are changed. The archived parameter behavior is also contextualized relative to get_reading_goal.

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 combination — 'Create, update, or archive a reading goal' — and explicitly distinguishes the operation from get_reading_goal and delete_reading_goal. An agent can immediately tell this is the write/upsert/archive tool for reading goals.

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 branching guidance: without an id, create or update based on matching metric and dates; with an id from get_reading_goal, edit that goal. It also names the alternative for permanent deletion — delete_reading_goal — and clarifies that archived=false restores rather than deletes.

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 past the annotations: it explains that null leaves a field untouched, that clearing a field is NOT supported, the cross-field side effect of edition_id on the reading edition, the error case when no edition exists, and which fields are echoed back. That is exactly the kind of hidden behavior an agent needs before a destructive upsert. It stops short of five only because the destructiveHint consequence (what a mistaken overwrite actually costs) is implied rather than stated.

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 operation and the field list, then the upsert rule, then the tricky owned/edition_id case, then sibling routing — a sensible ordering. It is dense with nested parentheticals, though, and a bulleted split of the owned semantics would read faster.

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?

Ten parameters, one required, no output schema — yet the description covers mutation semantics, the null-vs-clear rule, cross-field effects, an error condition, and the return fields. Nothing needed 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 already 100%, so baseline is 3; the description earns more by documenting the interaction between owned and edition_id (ownership of the given edition, falling back to the current edition, erroring if none) and the rating-to-user_rating rename. The remaining parameters are left to 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+resource ('Add a book to your library or update your entry') and immediately pins the operation type as an upsert. It enumerates the exact fields under scope and distinguishes itself from the read/list/delete siblings 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?

Explicitly routes three adjacent concerns to other tools: set_user_book_read for dates/progress, set_list_book for custom lists, delete_user_book for removal. The when-to-use question is answered without requiring the agent to compare schemas.

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 mutation profile (readOnlyHint=false, destructiveHint=true), but the description adds real context beyond them: partial-update semantics ('overwriting only the fields you pass'), the update-vs-create branch resolution logic, and the library-membership precondition. It stops short of warning about duplicate-read risk on repeated id-less calls, which matters given idempotentHint=false.

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 verb and the primary mode split, then the branch details, then the return value. Dense but nearly every clause carries decision-relevant information; the parenthetical examples ('a re-read or a past read with its own dates') are the only mildly expendable content.

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

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

With 8 optional parameters, no required fields, and no output schema, the description covers the decision logic (mode split), the precondition (library membership), and the return shape ('the read entry with its id'). 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 baseline would be 3, but the description goes further by explaining how `id`, `book_id`, and `user_book_id` relate and are mutually exclusive by mode, and where `id` comes from (get_user_book). That interplay is not expressed in the schema descriptions, which only state each field in isolation.

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 ('Log or edit reading dates and progress (pages or audiobook seconds)') and immediately splits the two operating modes by presence of `id`. It also names the sibling that supplies the id (get_user_book) and the sibling that must run first (set_user_book), so an agent can route 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 explicit when-to-use branches: with `id` to edit an existing read, without `id` to log a new one via book_id/user_book_id. It also states the precondition ('The book must already be in your library (add it with set_user_book)') and names the tool to call first, which is exactly the alternative-routing an agent needs.

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