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

The description indicates the tool creates an annotation (mutating action). With no annotations beyond title, it does not disclose permissions, rate limits, side effects, or response format. It adds basic behavioral context but lacks depth.

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 consists of two concise sentences: one for purpose and one for a key limitation. Every word adds value, with no redundancy or extraneous 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?

Given 9 parameters, no output schema, and no parameter descriptions, the description is incomplete. It fails to explain optional parameters or return values, leaving significant gaps for an agent attempting to use 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 0%, yet the description only explains 'quote' and 'note' implicitly. Parameters like kind, mood, tags, parentId, and quoteOffset are not described, leaving the agent with insufficient understanding despite containing 9 parameters.

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

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

The description clearly states the tool's purpose: 'Write a Claude margin annotation anchored to a quote in a chunk.' It uses a specific verb and resource, and distinguishes from sibling tools by noting that human private notes should use the HTTP reader API.

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

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

The description provides a clear guideline on when not to use this tool: for human private notes. However, it does not explicitly state when to use it or compare it to sibling tools like reading_list_annotations or reading_reply_to_annotation.

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 description's mention of 'browse' is consistent. It adds that pagination is used and images are not opened, but no further behavioral detail beyond what annotations imply.

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?

Single sentence, no extra words, front-loaded with purpose. Efficient and clear.

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, yet description does not describe what the response contains (e.g., list of card summaries, pagination metadata). Also fails to explain the bookId parameter. Incomplete for a tool with 3 parameters and no output schema.

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

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

Schema coverage is 0% and description provides no explanation for any of the three parameters (limit, bookId, offset). Even the word 'paginated' hints at limit/offset but does not define them or their defaults.

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 tool browses collected reading cards as a paginated collection without opening images. It clearly indicates listing over viewing individual cards, but it could more explicitly distinguish from reading_list_cards which may be a broader 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?

No guidance on when to use this tool versus siblings like reading_list_cards, reading_card_inbox, or reading_open_card. No when-not-to-use or alternative suggestions.

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, aligning with the description's 'Show' verb. The description adds a metaphor ('like a small bookmark inbox') but fails to detail behavior like ordering, pagination, or whether it shows all unread or only a subset.

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 a single concise sentence. However, the 'like a small bookmark inbox' analogy adds color but could be omitted without losing clarity, slightly reducing efficiency.

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

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

Given no output schema and 0% parameter documentation, the description lacks crucial details on return format, valid parameter values, and how this tool fits among 25 sibling tools. The metaphor does not compensate for missing technical specifications.

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 description provides no explanation for the two parameters (limit, bookId). The agent must guess their meaning from names alone, which is insufficient for effective use.

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 'Show unread collected reading-card prompts' clearly identifies the action and resource. It implies a list/filter operation distinct from siblings like reading_open_card or reading_dismiss_card, though the term 'prompts' could be more specific.

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 guidance on when to use this tool vs alternatives such as reading_list_cards or reading_card_collection. The comparison to a 'bookmark inbox' suggests a filtered view, but no explicit when-not-to-use or prerequisite mentions.

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 are minimal (only title), so the description carries full burden. It does not disclose side effects, idempotency, prerequisites, or what happens to previously collected cards. Only states the action and purpose, leaving behavioral traits unspecified.

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?

Extremely concise at 10 words, but this brevity comes at the cost of completeness. The description lacks necessary details and fails to front-load critical information for tool selection. Being too short reduces usability.

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

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

Given 14 parameters and no output schema or annotations, the description is severely incomplete. It does not explain the collect action's workflow, parameter usage, or return value. The tool's complexity demands far more context than provided.

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 14 parameters, none explained in the description. The description does not mention any parameter names, their roles, or how they relate to collecting a card. The tool's purpose is stated but disconnected from the input schema.

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

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

The description states it 'Collect[s] a small ritual reading card/bookmark' with purpose of revisiting later. The verb 'collect' and resource 'card/bookmark' are specified, but it lacks clarity on how 'collect' differs from 'save' (sibling 'reading_save_card' exists). The purpose is somewhat clear but not distinct enough.

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 guidance on when to use this tool versus alternatives like 'reading_save_card' or 'reading_open_card'. No mention of prerequisites or exclusion cases. The description provides no usage context beyond the basic 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=true, indicating no mutation. The description adds behavioral detail beyond annotations by explaining the fallback logic for omitted bookId, which is not captured in the schema or annotations. This is valuable for understanding tool behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two succinct sentences with no extraneous information. Every word adds value, directly addressing purpose and parameter behavior.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is largely complete. It explains the core function and parameter behavior. However, it does not describe return values or the format of the 'chunk', which could be inferred but is not explicit.

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 sole parameter 'bookId' has no description in the schema (0% coverage). The description fully compensates by explaining its optionality and default behavior, providing clear semantics that enable correct invocation.

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

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

The description clearly states the tool's purpose: 'Continue reading from the next unread chunk', specifying verb (continue reading) and resource (unread chunk). It distinguishes from siblings like 'reading_read_chunk' by implying automatic progression rather than reading a specific chunk.

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

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

The description provides usage context: 'If bookId is omitted, use the most recently read book.' This tells the agent when to use this tool (to continue reading) and how the optional parameter works, though it does not explicitly exclude alternative tools.

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 include destructiveHint=true. Description adds value by specifying that the book folder and related data are archived under 'data/trash', and that confirmation is required. This goes beyond the annotation 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?

Two sentences, no waste. Action and scope are front-loaded. All information is relevant and concise.

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?

Covers main behavioral outcome (archival) and a key requirement (confirm), but lacks mention of irreversibility, permissions, or error conditions. Adequate but not comprehensive for a destructive tool with no output schema.

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

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

Schema has 0% description coverage, so description must compensate. It only adds meaning for 'confirm' (requires true) but provides no explanation for 'bookId' (e.g., how to obtain it, format). Incomplete for both parameters.

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

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

Clearly states 'Delete a book' with specific verb and resource, and details what gets archived (folder, progress, annotations, etc.). Distinguishes from sibling tools like reading_list_books or reading_mark_read.

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?

Description mentions 'Requires confirm: true' but does not provide explicit guidance on when to use this tool versus alternatives (e.g., soft delete, mark as read). It implies deletion but lacks contextual usage boundaries.

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

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

With no annotations beyond a title, the description carries full burden. It discloses that dismissal is not deletion but fails to explain what dismissal entails (e.g., side effects, reversibility, required permissions). This is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single 12-word sentence with no fluff. The key action and resource are front-loaded, and every word contributes 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?

Given the tool's simplicity (1 parameter, no output schema, no annotations), the description is too sparse. It lacks guidance on response, error cases, or integration with sibling tools, making it hard for an agent to use correctly without additional context.

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

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

The schema has 0% description coverage for the single 'cardId' parameter. The description implies that the card must be a 'collected reading card' from the inbox, but does not explain how to obtain the ID, its format, or constraints, leaving key semantics ambiguous.

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

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

The description clearly states the verb 'dismiss', the resource 'collected reading card', and the location 'card inbox', distinguishing it from deletion. It differentiates from sibling tools like 'reading_delete_book' and 'reading_save_card' by specifying it does not delete.

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 mentions 'without deleting it' implying a non-destructive operation, but it does not explicitly state when to use this tool versus alternatives like 'reading_delete_book' or provide prerequisites such as whether the card must be collected.

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. The description adds that progress can be retrieved for one book or all books, but does not explain what progress entails (e.g., pages, percentage) or any other behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence of 8 words with the verb first. No wasted words.

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

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

For a tool with one optional parameter and no output schema, the description is minimal but adequate. It lacks explanation of the return format or what constitutes progress, which could leave the agent guessing.

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 by clarifying that providing bookId gets progress for that book, and omitting it gets progress for all books, adding meaning beyond the bare schema.

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

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

The description clearly states the tool retrieves reading progress for one book or all books. It distinguishes from siblings like reading_list_books and reading_list_annotations by specifying progress rather than listings.

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

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

The description implies usage for checking progress, and annotations confirm it's read-only. However, it does not explicitly state when not to use it or mention alternatives.

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 lacks disclosure of behavioral traits such as side effects, return values, or required subsequent steps (e.g., reading_import_part, reading_import_finish). Annotations only provide a title, so the description carries the full burden but fails to add meaningful behavioral 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 description is very short (two sentences), which is concise, but it sacrifices completeness. For a tool with many parameters and a multi-step process, a bit more detail would be warranted without becoming overly verbose.

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

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

Given the complex chunked import flow (with siblings like reading_import_part, reading_import_finish, reading_import_cancel) and no output schema, the description should provide more context about the overall import process and what to expect after calling this tool. It currently lacks this contextual completeness.

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 0% schema description coverage and 10 parameters, the description adds no meaning beyond the schema. It does not explain any parameter's role or constraints.

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

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

The description clearly states the verb ('start') and resource ('chunked EPUB/TXT import'), and explicitly distinguishes it from the sibling 'reading_import_book' by noting the use case for large files.

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 explicitly says 'Use this when the file is too large for one reading_import_book request,' providing clear guidance on when to use this tool versus an alternative.

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

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

No annotations are provided (only a title), so the description carries the full burden. It states 'Import' which implies a write operation, but it does not disclose side effects (e.g., overwriting existing books), error conditions, or any behavioral details beyond the basic action. For a tool with no annotations, more transparency 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?

The description is two sentences, directly states the purpose, and front-loads the key information. Every word is necessary and there is no redundant 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?

Given the tool has 10 parameters, no output schema, and no behavioral annotations, the description is severely lacking. It does not explain return values, error handling, or parameter details. The agent would have to rely solely on the schema, which for a complex import operation 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 input schema has 10 parameters (2 required) but the schema description coverage is 0%. The description only mentions 'base64 content' and 'EPUB or TXT file', providing no explanation for the other parameters such as title, author, format, maxChars, overwrite, etc. The description fails to add meaning beyond the schema.

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

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

The description clearly states the verb 'import', the resource 'one EPUB or TXT file', and the method 'from base64 content'. It also hints at the distinction from sibling tools by specifying 'for files small enough for one MCP request', which implies that larger files should use the import_begin/part/finish sequence.

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 explicitly advises when to use this tool: for files small enough for one MCP request. This implicitly tells the agent to avoid it for larger files and provides context for selecting among siblings. However, it does not mention prerequisites or explicitly state when not to use it.

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 explicitly states the destructive nature of the tool ('delete its temporary upload file'), which compensates for the lack of annotations like destructiveHint. However, it does not mention reversibility or side effects on other imports.

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 sentence that conveys the complete action without redundancy. Every word is necessary and contributes to understanding.

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

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

The description covers the primary purpose and outcome, but given the absence of an output schema and the simplicity of the tool, it would benefit from mentioning return values or error states for completeness.

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 required parameter uploadId has no description in the schema (0% coverage), and the description does not elaborate on what uploadId represents or its format, leaving the agent to infer context.

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

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

The description clearly states the action: cancel a chunked import and delete its temporary upload file. It uses specific verbs and resource terms, distinguishing it from other import-related siblings like reading_import_begin, reading_import_finish, etc.

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 when to use (when aborting an import), but does not provide explicit guidance on when not to use or alternative tools, such as reading_import_finish to complete the import instead.

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

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

No annotations provide behavioral hints, so the description carries full burden. It discloses the tool performs a write operation (adds to library) but fails to mention side effects, error states, or idempotency. Minimal transparency beyond the basic function.

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 a single sentence with no filler words, directly stating the action and outcome. It is front-loaded with the verb 'Finish'. However, it is arguably too concise, sacrificing clarity for brevity, which prevents a higher score.

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

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

The description lacks prerequisites or state requirements for the import, such as needing a prior reading_import_begin call. There is no output schema, and the return value is not described. For a tool in a multi-step process, this falls short of completeness.

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%, meaning the schema provides no parameter descriptions. The tool description does not explain 'uploadId' including its origin, format, or how to obtain it. The agent is left guessing what value to provide, which is insufficient.

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

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

The description clearly states the verb 'Finish', the resource 'a chunked import', and the outcome 'add the uploaded EPUB/TXT to the reading library'. It distinguishes itself from sibling tools like reading_import_begin and reading_import_part by specifying it is the final step.

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 after starting a chunked import but does not explicitly state when to use or not to use this tool. No alternatives or exclusions are mentioned, though the sibling list provides some context. 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?

The description discloses that the tool appends data, which is a mutation, but provides no information about side effects, error conditions, or behavioral constraints. Annotations offer no behavioral hints (e.g., no readOnlyHint or destructiveHint), so the description carries the full burden yet adds minimal detail.

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 extremely concise (one sentence, 8 words), which risks being underspecified. While there is no wasted text, the lack of parameter or context information suggests it is too sparse to be maximally helpful.

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

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

Given the complexity of a chunked import process and the lack of output schema or annotation richness, the description fails to situate this tool within the larger workflow. It does not indicate when in the sequence it should be invoked or what the expected result is.

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 input schema has three parameters with zero schema description coverage, and the description does not clarify their semantics (e.g., what 'uploadId' refers to, the role of 'index', or the expected encoding of 'dataBase64'). It adds no meaning beyond the schema field names.

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

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

The description clearly states the action and resource: 'Append one base64 file part to an active chunked import.' It distinguishes from siblings like reading_import_begin, reading_import_finish, and reading_import_cancel by specifying that it appends a part to an already active import.

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 the tool is for use during a chunked import, but it does not explicitly state prerequisites (e.g., must be used after reading_import_begin and before reading_import_finish) or when not to use it. No alternatives or exclusions are mentioned.

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

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

The description does not contradict the readOnlyHint annotation (it states a listing operation). However, it adds no behavioral details beyond the annotation, such as pagination, ordering, or sync behavior. The annotation carries the transparency burden, and the description is neutral.

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 a single sentence of 9 words with no wasted text. It front-loads the action and resource, then lists filters efficiently. Every word serves a purpose.

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

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

Given 6 optional parameters and no output schema, the description is minimal but covers the basic operation. It does not explain what annotations are, what fields are returned, or whether pagination exists. For a simple list tool with readOnlyHint, a score of 3 is adequate but not comprehensive.

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 mentions 4 of 6 parameters (book, chunk, kind, author) using natural language, but omits 'status' and 'parentId'. This adds some meaning but is incomplete, so a score of 3 is appropriate (baseline 4 minus 1 for missing two params).

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 explicitly states the verb 'List' and the resource 'annotations', and lists specific filter dimensions (book, chunk, kind, author). It clearly distinguishes from sibling list tools like reading_list_books and reading_list_chunks because it targets a different resource.

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 explicit guidance on when to use this tool versus alternatives. The description implies it is for listing annotations with optional filters, but does not mention exclusions or prerequisites. The usage context is derived only from the resource name.

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 set readOnlyHint=true; the description adds no additional behavioral context such as pagination or output format.

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?

Single sentence, front-loaded with key action and result; no wasted words.

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?

Despite simple parameters, lacks details on pagination, sorting, or scope; incomplete for a list tool with many 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?

With zero parameters, schema coverage is irrelevant. Description adds meaning by specifying output includes progress and annotation counts.

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

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

The description clearly states the tool lists imported books and includes progress and annotation counts, distinguishing it from siblings like reading_list_annotations and reading_list_cards.

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 guidance on when to use this tool vs alternatives like reading_list_annotations or reading_list_chunks; it simply states the function.

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 description doesn't need to restate it. The description adds context about filtering by completion status or shared moments, which is useful behavioral detail beyond annotations. No additional traits like pagination or sorting are disclosed.

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 a single sentence, but it includes jargon ('ritual,' 'margin moments') that may confuse the agent. It could be more concise and clear without sacrificing 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?

Given the tool has 5 parameters (none required) and no output schema, the description is too minimal. It does not explain what parameters do, what the output looks like, or how to use the tool effectively. More context is needed for proper invocation.

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

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

Schema description coverage is 0% (no parameter descriptions in schema), and the tool's description does not mention any of the 5 parameters (limit, scope, bookId, source, chunkId). Since coverage is low, the description must compensate, but it adds no parameter semantics at all.

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

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

The description clearly states the tool lists cards/bookmarks, specifying they are for 'completed sections or shared margin moments,' which helps distinguish from sibling list tools like reading_list_annotations. However, the phrase 'ritual reading cards' is slightly jargon-like, reducing clarity slightly.

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

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

The description implies usage context (listing cards for completed sections or shared margin moments) but does not explicitly state when to use this tool over alternatives, nor does it provide when-not or exclusion guidance.

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

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

Annotations already mark the tool as readOnlyHint=true, so the safety profile is clear. The description adds that the tool lists chunks 'in reading order,' which is a behavioral detail. However, it does not disclose other behaviors like return format, pagination, or potential rate limits, which would add value beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with no superfluous words. It is front-loaded with the purpose. Minor improvement could include brief context on what a 'chunk' is, but overall it is appropriately sized.

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

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

Given the tool's simplicity (one required parameter, no output schema, readOnly), the description provides a minimal but functional explanation. It lacks details on the return structure or paging, which for a listing operation might be expected. However, it is not critically incomplete for basic usage.

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 0% schema description coverage, the description must compensate. It mentions 'for a book' relating to the bookId parameter but provides no format, examples, or validation constraints. The parameter's meaning is implied but not explicitly explained.

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

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

The description clearly states the tool lists chunks for a book in reading order, specifying the action (list), resource (chunks), and scope (for a book, in reading order). It effectively distinguishes from siblings like reading_read_chunk (which reads a single chunk) and reading_search_chunks (which searches).

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 does not explicitly state when to use this tool versus alternatives or provide exclusion criteria. It implies usage for listing chunks in reading order but lacks guidance on scenarios where other list tools (e.g., reading_search_chunks) would be more appropriate.

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 description adds limited value beyond confirming read-only nature. It doesn't disclose pagination, ordering, or response structure, but is consistent with 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?

Single sentence is concise and front-loaded with the verb and resource. However, it omits parameter information that could be included without bloating.

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

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

Given four optional parameters and no output schema, the description is incomplete. It does not hint at parameter purposes or filter semantics, leaving the agent underinformed for effective invocation.

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

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

Four optional parameters (limit, bookId, chunkId, sessionId) have 0% schema description coverage and are not explained in the description. The description adds no meaning beyond the schema, failing to compensate for the 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?

Description clearly states 'List human note submission batches that have been shared with Claude', using specific verb and resource. It distinguishes from siblings like reading_read_submission (individual submission) and reading_submit_user_notes (creation).

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 guidance on when to use this tool versus alternatives like reading_list_annotations or reading_list_books. The agent is left to infer context without explicit when/when-not or sibling differentiation.

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 provide only a title, leaving the description to carry the burden of behavioral disclosure. The description mentions updating last-read progress but does not explain if the action is idempotent, reversible, or has side effects. No indications of required permissions or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely short (one sentence) and front-loaded with the core action. It is concise but at the cost of omitting useful details. Every word earns its place.

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

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

Given the lack of output schema, param descriptions, and behavioral details, the description is incomplete. For a simple action, it might suffice, but it fails to inform the agent about return values, state changes, or how it fits with 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?

Schema coverage is 0%, meaning the input schema provides no descriptions for bookId or chunkId. The description does not add any parameter meaning, leaving the agent to infer what these parameters represent.

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

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

The description clearly states the action (mark a chunk as read) and the resource (chunk), and distinguishes from sibling tools like reading_read_chunk or reading_get_progress. However, it could be more explicit about being a state update action.

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 guidance is provided on when to use this tool versus alternatives, such as reading_read_chunk to view content or reading_get_progress to check status. There is no mention of prerequisites or exclusion criteria.

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 description adds value by stating the output is an image for Claude to view. However, it omits behavioral details such as whether the card is marked as viewed, if there are size limits, or if the card must already be in a 'collected' state. The added context is minimal but non-contradictory.

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 a single sentence with no wasted words. It front-loads the verb and resource, and immediately states the output format. Every word is necessary and contributes to understanding.

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 read-only tool with one parameter and no output schema, the description covers the core behavior: opens a card and returns an image. It lacks error handling, success/failure signals, and the requirement that the card be 'collected,' but overall it is mostly complete given the low complexity.

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 0% schema description coverage, the description must fully explain the single parameter 'cardId'. It only implies it identifies the card ('Open one collected reading card') but does not specify format, source, or constraints (e.g., required length, how to obtain valid IDs from other tools). This is insufficient for an agent to correctly infer the parameter's meaning.

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

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

The description clearly states the action ('open'), the resource ('collected reading card'), and the output ('return it as an image for Claude to view'). It effectively distinguishes the tool from siblings like reading_collect_card or reading_save_card by specifying that it opens an existing card for viewing.

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 guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites (e.g., card must be collected), exclusions, or situations where another tool would be more appropriate. Among many sibling tools, this lack of differentiation leaves the agent uncertain.

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 annotation already declares readOnlyHint=true, so the description adds value by stating it returns prevId/nextId, but it does not disclose other behaviors like error handling or state effects.

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 very concise, with one sentence that contains the essential action. No redundant information, though it is quite minimal.

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

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

Given no output schema, the description should explain the full return value. It only mentions prevId/nextId, omitting the chunk content, which is the primary output. It also lacks context on prerequisites or error conditions.

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 has 0% description coverage for both bookId and chunkId, and the description does not add any meaning or format details. It fails to compensate for the missing schema descriptions.

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

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

The description clearly states it 'Read one book chunk' which is a specific verb+resource. It also mentions returning prevId/nextId, hinting at navigation, though it doesn't differentiate from siblings like reading_list_chunks or reading_mark_read.

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 guidance is provided on when to use this tool versus alternatives such as reading_list_chunks or reading_continue. The description lacks context for appropriate usage.

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 the description aligns with that. The description adds that the tool includes 'notes and context', which provides some behavioral context beyond the annotation, but no details on error handling or idempotency.

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 a single sentence that directly states the action and resource. It is efficient and free of unnecessary words, though it could include more detail without becoming verbose.

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

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

The description mentions 'notes and context' giving a vague sense of return content, but lacks specifics on structure, errors, or pagination. Given the tool has one parameter and no output schema, the description is minimally adequate but not comprehensive.

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 0% schema description coverage, the description does not add meaning for the 'submissionId' parameter. It implies the parameter identifies a 'submission batch' but does not explain how to obtain or format it.

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

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

The description uses the specific verb 'Read' and specifies the resource as 'one human note submission batch including notes and context'. It clearly distinguishes from sibling tools like 'reading_list_submissions' (list) and 'reading_submit_user_notes' (submit).

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 guidance is provided on when to use this tool versus alternatives. For instance, it doesn't contrast with 'reading_list_submissions' for retrieving multiple submissions or indicate if this tool should be used after submission creation.

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 implies a write operation but does not disclose behavioral traits like side effects, permission requirements, or what happens when parentId is invalid. No annotations provided beyond title, so the description carries the full burden and falls short.

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 a single concise sentence, which is appropriately brief for a straightforward tool, though it could benefit from structured bullet points or a clearer explanation of parameters.

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

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

Given the tool has 8 parameters with no param-level documentation and no output schema, the description is insufficient. It fails to explain the role of key optional parameters or the required parentId and note, leaving the agent to guess usage.

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 0% schema description coverage, the description adds no meaning to any of the 8 parameters. It mentions 'parentId' implicitly but does not name the parameter or explain others like kind, mood, tags, quote, etc.

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

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

The description clearly states the action (attach a reply) and the resource (under an existing annotation), distinguishing it from sibling tools like reading_annotate_passage (which creates new annotations) and reading_list_annotations (which lists).

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

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

No guidance on when to use this tool versus alternatives, such as reading_annotate_passage for creating new annotations. No exclusions or prerequisites mentioned.

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

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

Annotations only provide title, no destructiveHint or readOnlyHint. Description implies file creation side effect but lacks details on file format, naming, overwrite behavior, or error conditions.

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?

Single sentence with no filler, but could be improved by front-loading key action and separating return value. Short but not optimally structured.

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 only one parameter and no output schema, description should clarify 'collected' status, image file format, storage location, and absolute path semantics. Current description is incomplete for reliable agent invocation.

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

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

Schema coverage is 0%, so description must compensate. Description does not describe the 'cardId' format, valid values, or how to obtain it. No examples or constraints beyond 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?

Description uses specific verb 'Render' and specifies resource 'one collected reading card' and outcome 'local image file and return its absolute path'. This clearly distinguishes it from sibling tools like reading_open_card or reading_list_cards.

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 guidance on when to use this tool versus alternatives like reading_open_card. Does not state prerequisites (e.g., card must be collected) or mention when not to use it.

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 indicate readOnlyHint=true, consistent with search. The description adds no behavioral details beyond that—no mention of pagination (limit parameter), result format, or behavior when no results match. For a read-only search tool, this is minimal additional value.

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 a single efficient sentence, but it sacrifices completeness. It is not verbose but lacks crucial information about parameters and usage, making it an acceptable but not optimal length.

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

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

Given 3 parameters, no output schema, and zero schema descriptions, the description is too brief. It should explain the role of limit and bookId and hint at return types. The tool's complexity requires a richer description.

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 0% schema description coverage, the description must explain parameters. It mentions 'keyword' which maps to the 'query' param, but does not explain 'limit' (pagination) or 'bookId' (scoping). This leaves the agent guessing about two of three parameters.

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

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

The description 'Search book chunks by keyword' clearly states the verb (search), resource (book chunks), and method (by keyword). It is distinct from siblings like reading_list_chunks (listing without keyword) and reading_read_chunk (single chunk retrieval). However, it doesn't explicitly differentiate itself, which would earn 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 description provides no guidance on when to use this tool versus alternatives such as reading_list_chunks or reading_read_chunk. It lacks context about prerequisites, scope, or exclusions, leaving the agent to infer usage from the name alone.

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 discloses key behavioral traits: it includes chunk text by default once per session and marks notes as submitted to avoid resending. This adds value beyond annotations, but could further clarify what 'submitted' entails (e.g., irreversibility).

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 purpose, no wasted words. The description is efficiently structured.

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

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

Given 6 optional parameters and no output schema, the description is insufficient. It covers the basic purpose and default behavior but omits parameter explanations, expected outcomes, error cases, and prerequisites, leaving the agent guessing.

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 0% schema description coverage and 6 parameters, the description fails to explain any parameter's purpose or default values. The only hint is the phrase 'include each chunk's full text once per session' which loosely relates to contextMode, but no explicit parameter mapping is provided.

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

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

The description clearly states the tool submits open user notes for Claude review, with specific default behavior. The verb 'submit' and resource 'user notes' are precise, and the tool is distinct from sibling tools like reading_list_submissions and reading_read_submission.

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

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

The description implies usage for submitting user notes for review and notes the default behavior, but does not explicitly state when not to use it or list alternative tools. However, the context of sibling tools makes the usage clear.

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