Readlink

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description makes that concrete: "Adding a book that is already there just returns it" tells the agent no duplicate is created and no error is raised. It also discloses the default status applied when the optional parameter is omitted, which 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?

Three short sentences with no filler: purpose and default first, the required-id source second, idempotency last. Everything is front-loaded and each sentence carries distinct 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 two-parameter mutation with full schema coverage and no output schema, the description covers purpose, default behavior, and idempotency, which is what an agent needs to call it correctly. The only gap is that it never contrasts the tool with its shelf or wishlist siblings.

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 are already documented, so the baseline is 3. The description adds one genuinely new fact, the TO_READ default for the optional status field, but says nothing further about the enum values or the catalogId pattern.

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 ("Adds a book to the reader's library") and the parenthetical scope note ("Want to read by default") separates it from shelf and wishlist variants. It does not explicitly name the siblings it replaces, so the differentiation is implied rather than stated.

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 one concrete usage prerequisite, "Use a catalogId from search_books", which routes the agent to the right source for the required argument. It never states when to choose add_book_to_shelf or add_to_wishlist instead, so the when-not guidance 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 this is a non-read-only, idempotent, non-destructive, closed-world mutation, so the safety profile is largely covered. The description contributes the ordering dependency on library membership, which is genuinely beyond the annotations. It does not state what happens when the shelf is full, whether shelves are user-owned, or what the call returns.

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 short sentences with zero filler, and the action statement is front-loaded ahead of the precondition. Nothing is repeated from the title or 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 simple two-parameter tool with rich annotations and no output schema, the action and its prerequisite are adequately covered. The notable gap is identifier semantics — with 0% schema coverage, an agent still has to guess what userBookId refers to, which is the one thing the description should have closed.

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

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

Schema description coverage is 0%, so the description carries the full burden for two parameters, and it supplies none — shelfId and userBookId are never explained. The distinction between a catalog book id and a userBookId (library entry) is exactly the ambiguity an agent would trip over, and neither field's meaning nor format is clarified anywhere.

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 ("Puts a library book on a shelf") and implicitly distinguishes itself from add_book_to_library by naming that tool as a prerequisite step. An agent can tell the two apart, though the phrasing "puts ... on" is slightly informal compared with the sibling 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?

It gives an explicit precondition — the book must already be in the library, and add_book_to_library is named as the tool that satisfies it — which routes the agent to the correct alternative when the precondition fails. There is no guidance on when not to use it (e.g. book already on the shelf), but the idempotent annotation partly covers that 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?

Beyond the annotations (safe mutation, not idempotent), the description discloses a genuine side effect: chapterTitle silently creates a chapter if one with that title is missing. It also gives the length cap and default grouping behavior, though it doesn't mention any failure modes or what is 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?

Three tight sentences, front-loaded with purpose and then branching behavior. The 'Up to 2000 characters' line duplicates the schema maxLength slightly, but it sets a practical constraint the agent should know before composing.

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 five-parameter mutation tool with no output schema, the coverage is strong: creation side effects, defaults, and length limits are all stated. It stops short of covering the userBookId and page parameters, which an agent may guess but should not have to.

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 only 20% schema coverage, the description carries the parameter burden well: it explains the chapterId source, the create-on-miss behavior of chapterTitle, and the 'General notes' default. The userBookId and page parameters are left unexplained, which is the main 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 first sentence names a specific verb and resource ('Adds a note or a quoted passage to a library book'), which immediately distinguishes this from the sibling tools edit_note and delete_note.

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 explains the routing between chapterId (taken from list_notes) and chapterTitle, and states the fallback of 'General notes' when neither is given. It does not explicitly tell the agent when to use this tool instead of edit_note, but the create-versus-modify distinction is obvious from the verb.

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=true and destructiveHint=false, so safety and repeat-call behaviour are covered structurally. The description adds genuine context beyond them by stating the default-folder placement and the folderId override, but says nothing about duplicate handling, permission requirements, or failure modes.

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 short sentences with no filler; the primary action and its default behaviour come first, and the parameter-sourcing hint follows. Every clause conveys information an agent needs to select and invoke the 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?

For a two-parameter additive tool with no output schema and full annotation coverage, the description covers the essentials: what it writes, where it writes by default, and where the required ID comes from. Minor gaps are duplicate behaviour (partially covered by idempotentHint) and how to discover a folderId.

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 50%: catalogId is documented in the schema, while folderId carries no schema description. The description partially compensates by explaining that folderId overrides the default folder, which is the key semantic an agent needs, but it adds no guidance on obtaining a valid folderId (e.g., list_shelves or similar).

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 pairs a specific verb ("Saves") with a specific resource ("a book to the reader's wishlist"), which clearly separates it from sibling write tools like add_book_to_library and add_book_to_shelf. It stops short of naming those alternatives explicitly, so differentiation is implied by the resource noun rather than stated.

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 sentence "Use a catalogId from search_books" gives useful prerequisite/sourcing guidance and implies a search_books -> add_to_wishlist workflow. However, there is no when-not guidance and no explicit mention of add_book_to_library or add_book_to_shelf as alternative destinations, so the agent must infer the routing itself.

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, destructiveHint=false, idempotentHint=false and openWorldHint=false, so the mutation/non-idempotent profile is covered. The description adds that the resulting shelf is empty, which is useful context about the created state, but says nothing about duplicate-name behavior, failure modes, or what identifier is 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?

Two short sentences, zero filler, with the core action front-loaded before the constraint detail. Nothing could be removed without losing 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 single-parameter creation tool this covers the essentials, and annotations carry the safety profile. However, with no output schema the description should say what comes back (e.g., the new shelf's identifier) and whether duplicate names are permitted, which would materially affect how an agent calls it.

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

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

Schema description coverage is 0%, so the description must compensate; it does so partially by stating the 30-character name limit, which duplicates maxLength=30 in the schema rather than adding meaning. Nothing is said about uniqueness constraints, trimming, or allowed characters for the 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 (creates) plus resource (shelf) with the additional scope detail 'new, empty' that distinguishes it from add_book_to_shelf and rename_shelf in the sibling list. An agent can tell this creates a container rather than populating or modifying one.

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

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

The description implies usage (creating a shelf to organize books) but never states when to use this versus rename_shelf or get_shelf, nor any prerequisites such as needing an existing library. Usage is inferable from siblings but not spelled out.

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=true and readOnlyHint=false, so the safety profile is largely covered. The description reinforces this with 'This cannot be undone' and adds the reader-scope detail, but doesn't disclose what happens on an unknown or already-deleted ID, which matters for 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?

Two compact sentences with the action and its scope front-loaded and the irreversibility warning placed last for emphasis. No filler or redundant phrasing.

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 one-parameter delete with rich annotations and no output schema, this covers what is deleted, where it lives, where the ID comes from, and that it is irreversible. The only notable gap is behavior for an invalid or already-removed highlightId.

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

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

Schema description coverage is 0% for the single highlightId parameter, so the description must carry the meaning. It does add real value by pointing to list_notes as the source and tying the ID to highlights/bookmarks in the in-app reader, but it gives no format or constraint detail beyond the schema's length bounds.

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 ('Deletes a highlight or bookmark') and scopes it to 'made in the in-app reader', which separates it from note and shelf operations. It stops short of naming siblings like edit_highlight or delete_note, so differentiation is implied rather than explicit.

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

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

Provides clear context for when to call it: removing an existing in-app reader highlight or bookmark, with the ID sourced from list_notes. There are no explicit exclusions (e.g., 'use edit_highlight to modify instead') or error-handling guidance, keeping it below 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?

The description adds "This cannot be undone," which reinforces the destructive hint with plain-language consequences. It does not go beyond the annotations in any other way: nothing about required permissions, side effects on related entities, or what happens on repeat calls despite idempotentHint=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?

Two short sentences, both front-loaded and information-dense, with the destructive consequence placed immediately after the action. No filler or 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 simple two-parameter delete, the annotations already declare destructiveness and idempotency, and the description covers irreversibility and ID sourcing. The missing explanation of userBookId is the main completeness gap, and there is no output schema to compensate.

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

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

Schema description coverage is 0%, so the description carries the full burden, yet it only explains where noteId comes from and says nothing about userBookId, which is also required. One of two parameters is left completely undocumented in both schema and description.

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 ("Deletes one note") and constrains scope to a single note, which separates it from bulk or shelf operations. It does not explicitly contrast with the nearby delete_highlight or edit_note siblings, but the resource noun is unambiguous.

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 "noteId from list_notes" gives concrete guidance on how to obtain the required identifier, which is genuinely useful. However, there is no statement of when to prefer edit_note or how this differs from delete_highlight, so the guidance is implied rather than explicit.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description goes further by specifying exactly what is destroyed (the shelf, and the books only when deleteBooks is true) and that the operation cannot be undone. That is the highest-value information for a destructive tool and it is stated plainly.

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, front-loaded with the action and the cascade rule, then the irreversibility warning. No filler and nothing redundant with 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 two-parameter destructive tool with no output schema, the description covers scope of destruction, irreversibility, and confirmation requirements, which is nearly everything an agent needs. It omits edge behavior such as what happens if shelfId does not exist, a minor but real 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?

Schema coverage is 0%, so the description must carry the load, and it fully explains deleteBooks as the switch that cascades book removal versus leaving books in the library. shelfId gets no description, but its name and required status make it unambiguous in a single-identifier tool.

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 ("Deletes a shelf") and immediately disambiguates from the book-level siblings by explaining that the books themselves are not deleted unless deleteBooks is true. An agent can distinguish this from remove_book_from_shelf or remove_book_from_library without reading 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 clear procedural guidance: confirm with the reader first, and twice when deleteBooks is true, tied to the irreversibility of the call. It does not name an explicit alternative (e.g., rename_shelf or removing books individually) or state when-not to use it, 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=false, idempotentHint=true, destructiveHint=false, and the description adds real context beyond that: highlights can only be modified, not created, and passing null clears the note, which is a data-loss behavior the annotations alone do not convey. It falls short only on edge cases like an invalid or foreign highlightId and whether the caller must own the highlight.

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, front-loaded with the mutation, then the null-clear rule, then the sibling routing. No filler or repetition of 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 three-parameter mutation with no output schema and clear annotations, the description covers what changes, how to clear, where the ID comes from, and where not to use it. Remaining gaps are error behavior and return value, though annotations and the idempotent/last-write-wins semantics cover much of the risk profile.

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 0%, so the description must carry the load, and it does for the two ambiguous parameters: note is the reader's note and accepts null to clear, and highlightId is sourced from list_notes. The color parameter is only gestured at with 'its color', leaving the allowed enum values to the schema, and the 2000-character note limit is also schema-only.

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 (changes) and specific fields (note, color) on a specific resource (highlight from the in-app reader). It also disambiguates from siblings: highlightIds come from list_notes, new highlights are created in the reader, and add_note is the tool for quotes.

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 routing: use list_notes to obtain highlightId, note: null to clear, and add_note when the goal is saving a quote rather than editing an existing highlight. This is when-to-use, when-not-to-use, and the alternative in one short block.

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=true, and destructiveHint=false. The description usefully adds that existing text is replaced wholesale rather than appended or merged, which is real behavioral information. It says nothing about permissions, error conditions, or whether note metadata is preserved.

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 short sentence, front-loaded with the action and resource, with the parenthetical placed where it is useful. No wasted wording.

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 simple three-parameter mutation with no output schema, the description covers the core action and the noteId workflow. The unexplained userBookId and the lack of any note about overwrite consequences leave an agent with gaps before calling it.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It only explains noteId's source and leaves userBookId (why it is required alongside noteId) and the text field entirely unexplained beyond the schema's type and length limits.

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 ('Replaces the text of one note'), which separates it from add_note and delete_note among the siblings. It doesn't name those alternatives explicitly, but the operation is unambiguous.

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 '(noteId from list_notes)' implies the discovery workflow before editing, giving some implied usage context. There is no explicit statement of when to use this instead of add_note, delete_note, or edit_highlight.

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 safety is covered. The description adds genuinely new context beyond them: the call is free and does not consume the assistant allowance, which directly affects an agent's decision to call it speculatively, plus the fact that the quota is scoped to 'today'.

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, with the return content front-loaded before the cost caveat. Every clause carries information an agent would otherwise have to guess at.

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 no-argument read tool with no output schema, the description gives enough of the return shape (plan tier plus remaining assistant actions) and the cost profile to call it correctly. It stops short of naming the concrete fields or what a quota-exhausted state looks like, which would have made it fully self-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?

The tool takes zero parameters, so there is no parameter meaning to convey and the baseline is 4. The description correctly signals this by describing a self-scoped lookup of 'the reader's' account with no arguments required.

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 the specific resource (the reader's Readlink plan) and the specific measurement (assistant actions remaining today), so an agent knows exactly what comes back. It is clearly distinct from every sibling, which deal with books, shelves, notes and reading progress, though it never says so explicitly.

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?

Usage is only implied: an agent can infer this is the call to make when it needs to know the plan tier or remaining assistant allowance. There is no explicit when-to-use statement, no prerequisites, and no named alternative, but the zero-parameter shape makes the invocation unambiguous once the intent exists.

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 the safety profile is fully covered. The description adds a genuinely useful conditional behavior: reader status and rating appear only when the book is in the user's library. It does not discuss error behavior (e.g., what happens for an unknown ID/ISBN), which would have earned a higher score.

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, both front-loaded with the highest-value information (what is returned, then what input is accepted). 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?

With no output schema and no parameter descriptions, the description must explain both the return payload and the input format, and it does each in one clause. The only shortfall is that it lists returned fields without describing their structure, but for a single-record getter this is close to 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 description coverage is 0% and the single parameter is bare (just a string named "id"), so the description carries the full explanatory burden. It does that well by stating "Takes a catalogId or an ISBN," which tells the agent the ID is polymorphic — information found nowhere 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 ("Details of one book") and enumerates the returned fields: description, genres, series, page count, plus the reader's status and rating. It implicitly distinguishes itself from get_library_book by noting the library-specific data is included conditionally when the book is in the library, but it never names that sibling outright.

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 phrase "if it is in their library" hints at when the extra reader fields will be populated, which is useful context. However, there is no explicit guidance on when to call get_book vs get_library_book or search_books, and no prerequisites or exclusions 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 declare readOnlyHint, idempotentHint, non-destructive and openWorldHint=false, so the safety profile is covered. The description contributes the returned data surface (status, progress, dates, rating, review), which is genuinely useful given there is no output schema, but it says nothing about behavior on a missing or unauthorized userBookId, nor about whether a user-scoped credential is needed.

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 tight sentence with the resource front-loaded and the returned fields enumerated in priority order; nothing is padded. It is arguably too terse rather than too long, but as a structural matter it is clean.

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 one-parameter, non-destructive read whose annotations are fully populated, the description covers the resource and the returned fields, which is close to sufficient. The remaining gap is the meaning of userBookId and any failure semantics, which no other structured field supplies.

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

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

Schema description coverage is 0% for the single required parameter userBookId, and the description never mentions it. It does not clarify whether the id is a library-entry id versus a catalog book id or an ISBN, which is exactly the ambiguity that would cause a wrong tool call.

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 fragment "One book in the reader's library" plus the enumerable field list conveys retrieval of a single library entry, and the name get_library_book plus the title reinforce it. However, it lacks an explicit verb and never states how this differs from the sibling get_book (catalog lookup) or list_library, so an agent must infer the distinction from naming alone.

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?

There is no when-to-use guidance at all: no mention of when to prefer this over list_library for bulk retrieval, over get_book for catalog metadata, or over get_shelf for shelf context. Nothing tells the agent what prerequisites or conditions apply.

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 covered. The description adds nothing beyond that: no indication of what happens with an unknown or foreign shelfId, whether an empty shelf returns an empty list or an error, or whether results are paginated.

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 a single short phrase with zero padding, but it is a sentence fragment rather than a front-loaded statement of action. Briefness here comes from under-specification rather than discipline.

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 is the only source of return-value information, and it says only 'the books' without describing fields, ordering, or pagination. For a lookup tool keyed on an ID with no documented failure modes, this is insufficient.

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 shelfId parameter has 0% schema description coverage, so the description carries the full burden and largely fails it. The phrase 'one of the reader's shelves' hints that the ID is restricted to the authenticated reader's own shelves, but format, source (from list_shelves?), and error semantics are unstated.

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 fragment identifies the resource as the books on a single shelf, which usefully distinguishes it from the title's implication of returning shelf metadata and from list_shelves. However, there is no verb and no statement of what is actually done with those books (retrieved? listed? paginated?), leaving the purpose only implied.

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?

There is no guidance on when to use this versus siblings such as list_shelves (enumerate shelves), get_book (fetch a single book), or list_library. The agent must infer that this is the 'drill into one shelf' operation entirely on its own.

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 covered; the description usefully adds the default sort order (newest first) and the fact that filtering is optional. It does not address pagination behavior or whether any total count is returned, which are the remaining behavioral unknowns for a listing 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?

Two short sentences, zero filler, with the resource and ordering front-loaded before the filtering options. Nothing is redundant with the title or annotations.

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 four-parameter read-only list tool with no output schema, the description covers the core semantics but leaves the pagination story unexplained and gives no hint about what a result entry contains or how results are paged. Adequate to call the tool, but an agent must infer the limit/offset relationship from 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 only 25% (just the status enum restated), so the description carries real weight here; it does clarify that query is a title/author search that is distinct from status filtering. However limit and offset — including the 25 default and 100 cap — get no mention, leaving the pagination contract to the bare schema types.

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 resource (the reader's Readlink library), its default ordering (newest first), and its two filtering axes, so it is clearly a scoped listing of owned books rather than a general catalog search. It stops short of naming siblings like search_books or list_wishlist, which would settle the distinction outright.

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 implies usage via the filtering options ('Filter by reading status or by a title/author search'), which tells the agent this is the browse-and-filter path for the library. There is no explicit statement of when to prefer it over search_books (which presumably searches the whole catalog) or list_wishlist, and no exclusions.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value by disclosing the shape of what comes back (`chapters` with typed notes and quotes, `highlights` with marked passages), but says nothing about empty results, ordering, or pagination.

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 short sentences, front-loaded with the resource and then the returned sections, with no filler. The only structural weakness is the absence of an explicit verb in the opening 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?

With no output schema, the description must explain returns and it does give the top-level sections correctly. For a one-parameter read tool that is close to sufficient, but an agent still lacks guidance on empty results and on why this differs from get_library_book.

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

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

Schema description coverage is 0% for the single `userBookId` parameter, so the description carries the burden; 'A library book's notes' does imply the id refers to a library book rather than a catalog book, but no format, source, or failure behavior is given. Partial compensation for the coverage gap justifies the mid score.

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 identifies the resource precisely – a library book's notes and highlights, split into `chapters` and `highlights` – but never states an action verb. It reads as a noun phrase describing output shape rather than saying 'retrieve the notes and highlights for a book', so an agent must infer the operation from the name and title.

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?

There is no when-to-use guidance at all: nothing distinguishes this from get_book, get_library_book, or the add_/edit_/delete_note siblings, and no prerequisites or exclusions are given. The reference to a 'Notes & Highlights tab' implies a UI context but not invocation conditions.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so safety and idempotency are fully covered structurally. The description adds no behavioral context beyond that: no ordering, no indication of whether empty shelves are included, no scope relative to the reader's account, and no output shape (there is no 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?

It is a single short fragment with no wasted words, but the brevity comes from under-specification rather than tight writing. There is no front-loaded action statement to orient the agent.

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 zero-argument, read-only list tool with full annotation coverage, the bar is low, and the description at least establishes that the result is the reader's own shelf collections. However, with no output schema, an agent still gets no hint about the returned fields or ordering, leaving the definition only minimally complete.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning for the description to supply. Nothing is missing on this dimension.

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 is a noun phrase, 'The reader's shelves (their own collections of books)', which identifies the resource but never states a verb such as 'list' or 'retrieve all'. The action is only inferable from the tool name and title, and nothing distinguishes it from siblings like get_shelf or list_library.

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?

There is no when-to-use guidance and no mention of alternatives — an agent is not told to use get_shelf for a single shelf or list_library for books. The parenthetical clarifies what a shelf is conceptually, not when to call 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile needs no restating. Beyond that, the description discloses the non-obvious dual-mode behavior driven by folderId, which is a real trait an agent could not read off the annotations or schema. It stops short of covering pagination, ordering, or whether results are truncated.

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 short sentences, front-loaded with what the tool is before the branching behavior. Nothing is redundant and no sentence could be dropped without losing meaning.

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 optional-parameter read tool with full annotation coverage and no output schema, the description covers both branches and the content of each result set. The remaining gap is modest: it does not name the folder identifier source or note anything about result size, but an agent can call this correctly from what is given.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: it explains precisely what folderId changes about the result set in both presence and absence cases. What it does not clarify is where a folderId value comes from (i.e., that it is drawn from the folder listing produced by the no-argument call), which would have made it 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 description states the resource (the reader's wishlist) and spells out the two distinct result modes: folders when no folderId is supplied, books within a folder when it is. It is clear enough to distinguish from list_library and list_shelves by the word 'wishlist', though it does not explicitly contrast itself with 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?

It implicitly tells the agent how to use the single parameter (omit it to enumerate folders, supply it to enumerate books), which is genuine usage guidance. However, there is no explicit statement of when to reach for this tool versus list_library, list_shelves, or the add_to_wishlist counterpart, so the agent must infer placement in the workflow.

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 this is a non-readonly, non-idempotent, non-destructive write, and the description confirms it records data, so there is no contradiction. What is missing is the behavior an agent actually needs for a non-idempotent write: whether each call appends a new progress entry or overwrites the prior one, and whether currentPage may move backwards. Those gaps matter precisely because idempotentHint=false implies repeat calls are not free.

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 short sentences with zero filler, and the most decision-relevant fact, the choice between the two modes, is front-loaded. The parenthetical parameter names tie each mode to the schema directly.

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 three-parameter write tool with no output schema, the description covers the ambiguous part well but leaves the required userBookId undefined and says nothing about what the call returns or how progress is stored. Annotations cover the safety profile, so the remaining burden is modest but not fully met.

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

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

Schema description coverage is 0%, so the description carries the full burden and it does explain the meaning and mutual exclusivity of currentPage and pagesRead, which the schema alone does not convey. But userBookId, the sole required parameter, receives no explanation at all, and the description does not note that currentPage accepts 0 while pagesRead starts at 1. Two of three parameters are covered, so the baseline of 3 is fair.

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 ("Records reading on a library book") and then names the two distinct recording modes by their parameter names. An agent immediately knows this writes reading progress rather than book metadata. It does not explicitly contrast itself with the sibling set_reading_status, which is the main thing keeping it below a 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?

The constraint "Send exactly one" gives a concrete rule about how to call the tool, which is genuine usage guidance. However, there is no statement of when to prefer this over set_reading_status, or when logging progress is inappropriate. Usage must be inferred from the parameter semantics rather than read from an explicit 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?

Beyond the annotations it discloses two non-obvious behaviors: the write is published to the reader's public profile feed, and books absent from the library are silently added as Completed. That is exactly the side-effect detail an agent needs before invoking a write tool, and it is consistent with readOnlyHint=false and openWorldHint=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?

Two tight sentences with no filler: the action and its optional inputs first, then the library side effect, then the public-sharing warning. Every clause adds information an agent would otherwise have to guess.

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 three-parameter mutation tool with annotations and no output schema, the description covers the important unknowns: public visibility, the auto-add-as-Completed side effect, and rating granularity. It leaves out replacement semantics for existing ratings/reviews and what the response confirms, which is a modest gap rather than a blocking one.

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 only 33% (catalogId is the sole documented property), so the description carries real burden, and it partly meets it by spelling out the 0.5–5 half-star scale and that the review is short. It does not clarify whether supplying neither rating nor review simply shelves the book as Completed, nor whether a new review overwrites an existing one.

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 the reader's star rating ... and/or a short review") and adds the scope detail that a book not in the library is added as Completed, which separates it from the pure add_book_to_library path. It never names a sibling explicitly, so an agent must infer that reviews belong here rather than in add_note.

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 precondition — confirm with the reader first because the rating is shared on the public Readlink profile feed — which is genuine when-to-use guidance. It offers no explicit when-not cases or named alternatives (e.g. add_note for private notes, set_reading_status for status only).

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, and the description goes well beyond them by enumerating exactly what is destroyed: status, progress, rating, notes, highlights, and shelf membership. It also states irreversibility and mandates confirmation, which is the key behavioral fact an agent needs before invoking a cascading delete.

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 with no filler, and the cascade of what gets deleted is front-loaded followed by the irreversibility warning. Every sentence earns its place, though the ordering means the safety warning arrives after the bulk of the detail.

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 operation with annotations declaring the safety profile and no output schema, the description supplies the essentials: what is destroyed, that it is irreversible, and that confirmation is required. The only meaningful gap is that the sole parameter is never explained, which matters because its name is ambiguous against sibling 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 single parameter userBookId has no schema description at all (0% coverage), and the description never mentions it or clarifies that it is a library-entry identifier rather than a catalog book id. That distinction matters because siblings get_book and get_library_book both exist, so the description leaves a real ambiguity the schema cannot resolve.

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 ('deletes a book from the reader's library') with explicit scope: it removes the user's record of the book, not the book itself. The phrase distinguishes it from sibling tools like remove_book_from_shelf, delete_note, and remove_from_wishlist.

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 operating instruction ('confirm with the reader first') which frames the destructive context, but it never states when to choose this tool versus remove_book_from_shelf or when removal should be declined in favour of a lesser action. Usage context is implied by the destructive framing rather than explicitly routed.

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=true, and openWorldHint=false, so safety semantics are largely covered. The description adds the genuinely useful fact that only shelf membership is removed, not the book itself, but says nothing about behavior when the book is absent from the shelf or what the response contains.

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 short sentences with no filler, and the disambiguating fact about the book remaining in the library is placed immediately after the action. It is efficient, though the extreme brevity leaves little room for the missing parameter and precondition context.

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 two-parameter mutation, the annotations cover reversibility/idempotency and there is no output schema to explain. Still, with zero schema documentation the description should carry the parameter meaning and error conditions (book not on shelf, invalid ids), and it does neither.

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

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

Schema description coverage is 0% with two required parameters, and the description contributes nothing about them. In particular, userBookId versus a plain book id is ambiguous (the sibling get_library_book suggests a distinct identifier), and shelfId format is left entirely unexplained.

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 concrete verb and resource ("Takes a book off a shelf") rather than restating the name, and the second sentence distinguishes it from the sibling remove_book_from_library by clarifying the book record survives. It never names that sibling explicitly, so differentiation is implied rather than stated.

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 phrase "the book stays in the library" implicitly tells an agent when this is the right call versus a library-level removal, but there is no explicit guidance on alternatives (e.g., remove_book_from_library, delete_shelf) or preconditions such as whether the book must already be on the shelf.

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 disclose the important behavior here: destructiveHint=true, idempotentHint=true, readOnlyHint=false, so an agent knows this mutates state and that repeating it is safe. The description adds the sourcing of the identifier but says nothing further about effects, such as what happens if the book is not on the wishlist or whether library data is affected.

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 short sentences with no filler, and the core action is stated first before the example and the parameter hint. Every clause 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 single-parameter, purely destructive removal with full annotation coverage, the description covers purpose, trigger, and where to obtain the ID. The only real gap is the return/confirmation behavior, but no output schema exists and the annotation set already signals idempotency.

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

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

Schema description coverage is 0%, so the description must carry the parameter meaning, and it does the most useful thing possible: it tells the agent to take the bookId from list_wishlist. Format and length constraints remain undocumented, but the critical sourcing guidance is present.

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 ('takes a book off the wishlist') and adds a concrete example of when that state occurs. The resource ('wishlist') implicitly separates it from remove_book_from_library and remove_book_from_shelf, though it never states the contrast explicitly.

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 supplies a clear usage scenario ('once it is added to the library') that tells an agent when this tool is the right call. It stops short of stating any exclusions or naming the alternative actions an agent should consider instead, so it is clear context rather than full when/when-not 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 the full safety profile: non-read-only, idempotent, non-destructive, closed-world. The description adds nothing beyond them — it does not say whether renaming to a name that already exists errors, whether the old name is freed, or what a failure looks like. The only extra detail, "up to 30 characters," merely restates the schema's maxLength.

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 short sentence with the resource and constraint front-loaded and no filler. It is tight, though its brevity reflects under-specification rather than disciplined economy.

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 two-parameter mutation, the annotations cover safety and idempotency and there is no output schema to explain, so the core call is callable. What remains missing is meaning for shelfId and any note on name collisions or error behavior, which the agent would need to call this correctly in edge cases.

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

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

Schema description coverage is 0%, so the description must carry the param burden, and it does not. It hints at the name parameter's length bound (already enforced by maxLength: 30) but says nothing about shelfId — its format, where to obtain it, or what happens if it doesn't resolve to an existing shelf.

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 ("Renames one of the reader's shelves"), which is unambiguous on its own. It does not differentiate from adjacent siblings such as create_shelf, delete_shelf, or list_shelves, so an agent still has to infer that this only modifies an existing shelf.

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?

No when-to-use or when-not-to-use guidance is given; the description never contrasts this with create_shelf or delete_shelf, nor states prerequisites such as the shelf already existing. The implied usage (modify an existing shelf) is inferable only from the verb "Renames".

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 and scope are covered. The description adds value beyond them by disclosing what is returned: catalogIds plus per-book library/wishlist status flags, which is important since there is no output schema. It omits result ordering and behavior on zero matches, keeping 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?

Two sentences, zero filler, and the purpose is front-loaded before the return-value detail. Every clause 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?

For a two-parameter read-only search with strong annotations and no output schema, the description covers purpose, match fields, return contents, and downstream workflow. The remaining gap is the undocumented limit defaults and result ordering, which is minor but not negligible.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It successfully explains that the query string matches title, author, or ISBN, which is real added meaning. However, the limit parameter (default 5, max 10) is not mentioned at all, leaving half the parameters undocumented anywhere.

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 ('Search Readlink's book catalogue') and names the searchable fields (title, author, ISBN). It also distinguishes catalogue search from library listing by noting the results report library/wishlist membership, so an agent can tell it apart from siblings like list_library or get_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?

Usage is implied rather than stated: the phrase 'Returns catalogIds to use with the other tools' signals this is a discovery step that feeds get_book, add_book_to_library, and similar tools. However, there is no explicit when-to-use/when-not guidance, no mention of using list_library or list_wishlist instead when the reader already knows what they want.

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=false, idempotent=true, destructive=false, closed-world, so the safety profile is covered; the description's genuinely additive fact is that dates default to today and can be nulled when unknown. It does not say what happens to existing startedOn/finishedOn values when the status changes, whether progress is reset, or what error surfaces if userBookId is not in the library - relevant for a mutation.

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, front-loaded with the verb and the state values, with no filler. Deduction because "Dates default to today" uses a vague collective noun instead of naming startedOn and finishedOn, forcing the agent to map it back to 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 4-parameter mutation with 25% schema coverage, no output schema, and four annotations, the definition is adequate but thin: it explains date defaulting yet omits the status/date interaction, the source of userBookId, and failure conditions. Enough to attempt a call, not enough to call it confidently in edge cases.

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 only 25% (only status is described), so the description must compensate: it usefully clarifies the enum states and the default/null semantics of the two date fields. However it never explains userBookId (presumably from list_library/get_library_book) or which date belongs to which transition, leaving half the parameter meaning implicit.

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?

"Moves a library book to TO_READ, READING or COMPLETED" gives a specific verb (moves), a specific resource (library book), and the exact state machine values, so an agent knows it is a status mutation. It falls short of 5 because it never names the sibling it is not - notably log_reading_progress, which also changes reading state - so the boundary must 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?

There is no when-to-use or when-not-to-use guidance; the description never mentions log_reading_progress, rate_book, or get_library_book, despite a large sibling set with overlapping concepts. The only conditional instruction is about passing null for dates, which is a parameter rule rather than a selection rule.

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