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

With annotations carrying only a title, the description carries most of the behavioral burden. It discloses that the operation writes an annotation, that the annotation is a Claude margin annotation rather than a user note, and that it is quote-anchored. It does not cover failure behavior, permissions, idempotency, or what the created annotation looks like, which are meaningful gaps 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?

Two sentences, no filler: the first names the core operation and the second gives an important exclusion. The main information is front-loaded and every sentence earns its place.

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

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

For an 8-parameter tool with no output schema, no annotation behavioral hints, and 0% schema coverage, the description leaves too much implicit. It gives the core intent and a boundary, but an agent still cannot confidently determine how to populate optional fields or what to expect after 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 the description must compensate for undocumented parameters. It implicitly explains quote and chunkId through 'anchored to a quote in a chunk,' and note via 'annotation,' but it says nothing about bookId, kind, mood, tags, or parentId. With eight parameters, this 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 opens with a specific verb and resource: 'Write a Claude margin annotation anchored to a quote in a chunk.' It clearly distinguishes this tool from human-note submission by declaring that human private notes should be created through the HTTP reader API, not this MCP tool.

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 when-not: human private notes should go to the HTTP reader API rather than this tool, and the quote/chunk anchoring tells the agent the intended target. It does not explicitly route to sibling tools like reading_reply_to_annotation for follow-up replies, so it stops short of full alternative guidance.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict this. It adds some useful behavioral context by stating the collection is paginated and scoped to 'collected' cards, but it does not disclose details about ordering, response shape, or how pagination behaves.

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 is front-loaded with the core action and resource, and it wastes no words. It earns its place by communicating the essential distinction without opening every image.

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 three undocumented parameters, the description is too sparse to fully support correct invocation. It does not explain what limit/offset/bookId control, how 'collected' relates to the bookId filter, or what the paginated response will look like. The read-only annotation helps, but the description still leaves significant gaps.

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 for the three undocumented parameters. It only implies limit and offset through the word 'paginated' but provides no meaning for bookId or the parameter semantics. This leaves an agent with little guidance for constructing correct calls.

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 identifies the action (browse), the resource (collected reading cards), and the mode (paginated collection). It also contrasts with opening every image, which helps distinguish it from more granular viewing tools. However, it does not explicitly differentiate itself from the similarly named sibling 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?

The phrase 'without opening every image' implies this is for high-level browsing rather than inspecting individual cards, giving some situational context. It does not explicitly state when to prefer this tool over alternatives such as reading_list_cards or reading_open_card, nor does it mention exclusions or prerequisites.

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 readOnlyHint annotation already covers the read-only safety profile. The description adds the meaningful 'unread' and 'collected' filter semantics, which are behavioral traits. It does not disclose ordering, pagination, or whether viewing affects state, but these are minor given the read-only annotation.

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, front-loaded sentence that states the action and resource before the illustrative analogy. Every word earns its place, with no redundancy or filler.

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

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

The core purpose is clear enough for a basic invocation, and the read-only annotation covers side-effect concerns. However, with no output schema and 0% parameter documentation, the meaning of limit and bookId is left entirely to inference, so the description is only minimally complete for a two-parameter tool.

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

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

Schema description coverage is 0%, and the description never mentions limit or bookId. An agent must guess that limit caps the number of results and bookId filters by book, so the description entirely fails to add meaning beyond the bare property names and 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 uses a specific verb and resource: 'Show unread collected reading-card prompts.' The 'small bookmark inbox' analogy reinforces a distinct scope, differentiating it from listing all cards or mutating actions like reading_save_card/reading_dismiss_card.

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: use this when the user wants unread collected reading-card prompts. However, the description does not explicitly contrast it with siblings like reading_list_cards, nor does it provide when-not-to-use guidance, leaving some routing 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 provide only a title, so the description bears the full burden of behavioral disclosure. It implies persistence ('so it can be revisited later') but does not state whether this creates, updates, or moves data, what side effects occur, or what the return value is.

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 redundant phrasing, but the structure is too sparse for a tool with 14 parameters. It front-loads the action but omits necessary 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?

With 14 parameters, no output schema, no annotation-based safety hints, and many sibling tools in the same card/save domain, this description is far too incomplete. An agent cannot reliably determine what inputs to supply or what invoking this tool accomplishes.

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 14 parameters with 0% description coverage, and the description adds no parameter-level meaning. None of the parameters like art, scope, chunkId, or variant are explained, leaving an agent unable to determine what values are appropriate.

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

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

The description states a clear action ('Collect') and resource ('reading card/bookmark'), with a stated purpose of revisiting later. However, it does not differentiate 'collect' from sibling tools like reading_save_card or reading_card_collection, and the word 'ritual' adds ambiguity.

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 tool versus alternatives such as reading_save_card, reading_dismiss_card, or reading_card_inbox. The purpose clause is too generic to establish selection 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?

The annotations already declare readOnlyHint=true, so no mutation warning is needed. The description adds useful stateful behavior by explaining that the tool advances through unread chunks and relies on the most recently read book when no bookId is supplied. No contradiction with the annotations exists.

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 short sentences with no filler. The main action is front-loaded, and the optional behavior is stated second, making it easy for an agent to parse quickly.

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 tool with one optional parameter and no output schema, the description covers invocation and the key default behavior. It does not define exactly what "next unread chunk" means in terms of progress state, but the concept is reasonably inferable and the annotations cover the read-only nature. Overall, it is sufficiently complete for the tool's 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?

The schema only defines bookId as an optional string with no description, so the description carries the semantic burden. It effectively conveys that bookId selects which book to continue and that omitting it falls back to the most recently read book. It could explicitly state that bookId identifies the book, but the intended meaning is clear.

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

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

The description clearly states a concrete action and resource: "Continue reading from the next unread chunk." It also clarifies the optional bookId scope, but it does not explicitly name or distinguish itself from sibling tools like reading_read_chunk, so the differentiation is implicit 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?

The description makes the usage context clear: this tool is for resuming reading at the next unread chunk, and it explains the fallback to the most recently read book when bookId is omitted. It does not explicitly state when not to use it or name alternatives, but the intended scenario is evident.

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 carry a title, so the description carries the burden of behavioral disclosure. It clearly states the primary action (dismiss from the inbox) and a key side-effect boundary (does not delete the card), which is useful safety-relevant context. It does not discuss reversibility or persistence details, but for a simple single-parameter action this is adequate.

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, front-loaded sentence with no filler. It delivers the action, the scope, and the non-deletion caveat in minimal 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 tool with one required parameter and no output schema, the description is nearly complete: it identifies the input (a collected card from the inbox) and the result (dismissed, not deleted). It lacks explicit guidance on obtaining the cardId, but sibling tools such as reading_card_inbox and reading_list_cards cover that 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?

Schema description coverage is 0%, so the description must compensate. It clarifies that the single parameter refers to a collected reading card from the inbox, but it does not explicitly state where cardId comes from or its expected format. This is modest compensation, not complete.

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 clear verb ('Dismiss') and resource ('collected reading card from the card inbox'), and explicitly distinguishes the action from deletion with 'without deleting it.' This separates it from sibling operations like collect, save, or open.

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: this tool is for collected cards currently in the card inbox, and the non-deletion clause signals when not to use it. It does not explicitly name alternative tools, but the inbox and non-deletion framing make the appropriate use case evident.

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 readOnlyHint=true. The description goes beyond by revealing normalization behavior and the capped, truncated context-chunk return. It does not discuss rate limits or failure behavior, but these are secondary for a read-only lookup.

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

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

Single sentence that front-loads the action and includes only high-value details: normalization and context-chunk count. No filler or repetition of the tool name/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 5-param tool with no output schema and no param descriptions, the description conveys the core behavior and a rough idea of the response (up to three truncated chunks) but omits meaning of limit, bookId, maxContextChars, and any defaults. It gives enough for a simple quote lookup but not enough to confidently invoke all capabilities.

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 zero description coverage across 5 params, and description only implicitly addresses quote and contextChunkLimit/maxContextChars via 'short quote', 'up to three', and 'truncated'. bookId, limit, and maxContextChars semantics are not explained, so the description does not compensate for the schema gap.

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

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

States a specific verb (Find) and resource (short quote/line across book text), and adds the distinguishing detail of punctuation/spacing normalization. This differentiates it from sibling search/list tools even without explicit comparisons. The output of neighboring chunks is also specified, so an agent can anticipate the result.

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 when/when-not with alternatives, but the description gives clear context: use when you have a short quote whose exact punctuation/spacing may differ. It does not mention reading_search_chunks or when to use that instead, so it stops short of full 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=true, so no read-only claim is needed. The description adds the one-book/all-books behavior, which is useful context beyond the annotation, but it does not disclose return format or aggregation details. No contradiction 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?

The description is a single efficient sentence with no filler. The key scoping decision is 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?

For a simple one-parameter read-only getter with no output schema, the description covers the only decision an agent needs to make: whether to target one book or all. No prerequisites, side effects, or complex alternatives are needed at this complexity level.

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 burden of explaining bookId. It does so effectively: bookId present means one book, absent means all books. This adds real meaning beyond the schema's bare string type.

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 ('get'), a clear resource ('reading progress'), and the exact scope ('one book or all books'). This distinguishes it from sibling tools like reading_list_books and reading_continue without requiring the schema.

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

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

The description implies this is the tool for retrieving progress, and the optional bookId suggests single-book vs all-books usage. However, it provides no explicit guidance on when to prefer this over related siblings, nor any exclusions or 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?

Annotations only provide a title, so the description must carry the full behavioral burden. It discloses that the import is chunked, but it does not explain what calling this tool actually creates or changes, whether it returns an import ID, how overwrite behaves, or what state/context is required for subsequent calls.

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

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

The description is compact, front-loaded with the core operation, and contains no filler. Both sentences earn their place: one states the action, the other gives the usage condition.

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 workflow, 10 parameters, no output schema, and siblings like reading_import_part, reading_import_finish, and reading_import_cancel, this description is far too incomplete. It does not explain what happens after calling begin, what identifier is used to continue, or how the chunks connect to the final import.

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 meaning for any of the 10 parameters. The required filename, optional title/author/bookId, maxChars, expectedBytes, headingRegex, and other parameters are all left unexplained, forcing the agent to guess.

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 operation ('Start a chunked EPUB/TXT import') and clearly identifies the resource and mode. It also distinguishes itself from the sibling reading_import_book by noting the 'too large for one request' condition.

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 states when to use this tool: when the file is too large for a single reading_import_book request. It names the alternative tool and gives a clear routing rule for an agent.

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 readOnly or destructive annotations except a title, the description carries the full burden of behavioral disclosure. It explains the basic import action and base64 input, but does not mention overwrite behavior, side effects on existing books, or what happens after import. This is thin for a mutating 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 two tight sentences with no filler. The core action is front-loaded, and the usage qualifier earns its place by routing the agent to the single-request import path.

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

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

There is no output schema and no behavioral annotations, yet the tool has 10 parameters and sits in a family with multi-part import tools. The description covers the simple happy path but is not complete enough to inform an agent about optional sectioning/overwrite behavior or the expected result of a successful import.

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 there are 10 parameters, so the description must compensate. It adds minimal meaning by clarifying dataBase64 is base64 file content and that the file is EPUB or TXT, but it leaves filename, overwrite, maxChars, headingRegex, minSectionChars, title, author, and bookId 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?

The description states a specific action and resource: import one EPUB or TXT file from base64 content into the reading library. It also distinguishes itself from multi-step import siblings by emphasizing 'small enough for one MCP request', so an agent can tell it apart from reading_import_begin/part/finish.

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 gives a clear usage condition: use for files small enough for a single MCP request. This implies larger files should go through the multi-step import flow, though it does not explicitly name those sibling tools or state a hard 'do not use for large files' exclusion.

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 behavioral annotations other than a title, the description carries the burden of disclosing side effects. It clearly states that the operation cancels the import and deletes the temporary upload file, which is meaningful destructive context. It does not mention idempotency, irreversibility, or what happens to already-uploaded parts, but the core effects 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, front-loaded sentence with no filler. It names the action and the key side effect efficiently, earning its place entirely.

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 tool, the description gives the basic purpose and a key side effect, but it omits usage timing relative to the sibling import tools and the source of the uploadId. These are meaningful gaps despite the tool's simplicity.

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

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

Schema description coverage is 0%, so the description needs to compensate for the single 'uploadId' parameter, but it does not mention it at all. The parameter name is somewhat self-explanatory, but the description never says the uploadId is the import identifier or how to obtain it, leaving a gap.

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

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

The description states a specific action, 'Cancel a chunked import', and adds the concrete consequence of deleting the temporary upload file. This clearly distinguishes it from the import lifecycle siblings such as reading_import_begin, reading_import_part, and reading_import_finish.

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 gives no explicit guidance on when to use this tool versus alternatives, such as 'use reading_import_finish to complete successfully' or 'use this when aborting an import'. The intended usage is only implied by the verb 'cancel' and the sibling tool names.

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, so the description carries the full burden of behavioral disclosure. It conveys that the operation is a mutating finalization that adds a book to the library, but it does not disclose whether the operation is idempotent, what state the import must be in, whether it is irreversible, or what happens if called prematurely. This leaves the agent to infer key side effects for a write operation.

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

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

The definition is a single sentence with the key verb 'Finish' front-loaded, no filler, no repetition of schema or annotations. Every part contributes purpose and outcome.

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 tool with no output schema, the description covers the core action and effect. It is incomplete, though, in the context of the multi-step import workflow: it omits the required prior state (all chunks uploaded after reading_import_part) and any indication of success/failure behavior, which an agent needs to call it correctly.

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

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

With schema description coverage at 0%, the description needed to explain uploadId but never mentions the parameter by name. The phrase 'uploaded EPUB/TXT' weakly implies uploadId is the identifier of a previously started upload, but it does not state where that ID comes from (e.g., reading_import_begin) or what value is valid.

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 opens with 'Finish a chunked import,' a specific verb and resource that clearly marks it as the completion step for the chunked-upload family (begin/part/cancel/finish). The added effect, 'add the uploaded EPUB/TXT to the reading library,' distinguishes its outcome from reading_import_cancel and other 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?

The phrase 'Finish a chunked import' implies it should be used after reading_import_begin and reading_import_part, and it is implicitly the counterpart to reading_import_cancel. However, it never explicitly states this precondition, tells the agent not to call it before all chunks are uploaded, or contrasts with cancel.

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 no behavioral hints, so the description carries the full burden. It communicates that the operation appends data and requires an active import, but it does not explain ordering, idempotency, effects of invalid uploadId, failure behavior, or what happens after the final part is appended.

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 focused sentence with no filler. It front-loads the core action and resource, making it easy to scan and quickly understand the tool's role.

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 three undocumented parameters, no output schema, and no behavioral annotations, this one-liner is insufficient. It does not explain the chunk sequencing, required upload ID origin, the role of index, or what a successful append implies for the overall import workflow.

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It clarifies that the part is base64-encoded, which helps for dataBase64, but uploadId is only vaguely implied by 'active chunked import', and index is not explained 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 uses a specific verb ('Append'), a clear resource ('one base64 file part'), and a scoping context ('an active chunked import'). This clearly distinguishes it from siblings like reading_import_begin, reading_import_finish, and reading_import_cancel.

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 'to an active chunked import' gives clear contextual guidance that this tool must be called after a chunked import has been started and before finish/cancel. It does not explicitly name alternatives or exclusions, but the timing is reasonably clear.

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

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

The readOnlyHint annotation already signals a safe read operation, and the description adds the behavior of optional filtering. It does not disclose pagination, ordering, default scope, or response shape, but with the annotation covering safety, this is a modest but acceptable level of transparency.

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

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

The description is one tight, front-loaded sentence with no filler. It states the core action first and then the optional filters, which is exactly the right structure.

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 filtered-list read operation, the description is minimally adequate, especially with readOnlyHint present. However, with no output schema and no mention of status/parentId or list response details, an agent gets only a partial picture of what this tool returns and how to scope 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 carries the burden of explaining parameters. It maps four of the six schema fields (kind, author, book, chunk) to filter concepts, but it omits status and parentId entirely and provides no value format or enum guidance. This is only partial compensation for the complete lack of 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 uses a specific verb ('List') and resource ('annotations'), and mentions the optional filter dimensions. This clearly distinguishes it from sibling list tools like reading_list_submissions, reading_list_chunks, and reading_list_books.

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

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

The intended use is implied by the name and description: call this when you need annotations rather than submissions, chunks, or books. However, it does not explicitly state when not to use it or point to alternatives, leaving the agent to infer the routing from the tool 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 annotations already declare readOnlyHint=true, so the description does not need to cover safety. It adds that results include progress and annotation counts, but does not disclose ordering, pagination, or response format; these gaps are minor for a simple read-only list.

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 front-loaded sentence with no filler. It states the action, resource, and key returned data efficiently.

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-parameter, read-only list tool, the description is complete enough. It says what is listed and what information is included, so an agent can invoke it correctly without additional details.

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 zero parameters and schema description coverage is 100%, so the baseline of 4 applies. There are no parameter semantics for the description to add.

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 'List' with a clear resource ('imported books') and states the returned data (progress and annotation counts). This distinguishes it from sibling tools like reading_list_annotations, reading_list_chunks, and reading_get_progress.

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 intended use is implied: call this when you want an overview of imported books with progress and annotation counts. However, it does not provide explicit when-to-use vs. when-not-to-use guidance or name alternatives, so it relies on inference.

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

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

Annotations already declare readOnlyHint=true, and the description does not contradict that. It adds some behavioral context by stating that the returned items are "collected" and tied to "completed sections or shared margin moments," but it does not disclose ordering, default limits, or response shape.

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

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

The description is a single concise sentence with no filler and front-loads the main action. The phrase "shared margin moments" is somewhat vague, but the overall structure is efficient.

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 is not adequate for a list tool with five optional parameters, no output schema, and a large sibling set. An agent cannot determine how to construct a valid call, what the returned cards look like, or how this tool differs from other card-related 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 description coverage is 0%, and the description provides no parameter-level meaning. It does not explain limit, scope, bookId, source, or chunkId, nor how they filter results. With five undocumented parameters, the description fails to compensate for the missing schema information.

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

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

The description uses a clear verb ("List") and a specific resource ("collected ritual reading cards/bookmarks"), and adds a scoping qualifier ("for completed sections or shared margin moments"). It does not explicitly differentiate from sibling tools like reading_card_collection or reading_card_inbox, but the domain is reasonably clear.

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

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

The description does not state when to use this tool versus alternatives such as reading_card_inbox, reading_card_collection, or reading_list_annotations. No exclusions, prerequisites, or selection guidance are provided, leaving the agent to guess based on tool names.

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 the useful behavioral detail that results are ordered by reading order, but it does not disclose things like pagination, return format, or whether chunk content is included.

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, front-loaded sentence with no filler. Every word earns its place: it names the action, the target, the scope, and the ordering in minimal space.

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

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

For a simple one-parameter list operation with readOnlyHint=true and no output schema, this description gives enough information to invoke the tool correctly. It could be slightly richer by indicating what each listed chunk contains, but the core calling context is complete.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented bookId parameter. It only says 'for a book', which merely restates that bookId identifies a book and adds no new detail about how to obtain, format, or validate the ID.

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

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

The description uses a specific verb ('List') and resource ('chunks') plus an explicit scope ('for a book') and ordering ('in reading order'). This clearly distinguishes it from sibling tools like reading_read_chunk and reading_search_chunks, which have different purposes.

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 that this tool is for enumerating a book's chunks in order, but it does not explicitly state when to prefer this over reading_search_chunks or reading_read_chunk. No alternatives or exclusions are mentioned, leaving usage 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 establish readOnlyHint=true, so the description's 'List' verb is consistent. The description adds the useful scoping detail that only submission batches 'shared with Claude' are returned, which is not visible in the schema. However, it does not disclose behaviors like pagination, default limits, or filtering 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 a single, tightly-scoped sentence with no filler. It front-loads the action and resource with a useful qualifier, making it highly efficient for its 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?

With four optional parameters and no output schema, the description should at least hint at how filters are used and what a returned batch looks like. It does neither. The only added context is the 'shared with Claude' scoping, which is insufficient for an agent to confidently call the tool with correct parameters.

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 burden of explaining parameters. It does not mention limit, bookId, chunkId, or sessionId at all. The parameter names are somewhat intuitive, but the description adds no meaning beyond the raw 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 uses a specific verb ('List'), names the exact resource ('human note submission batches'), and adds a meaningful scope ('shared with Claude'). This differentiates it well from siblings like reading_read_submission (singular tool) and reading_list_annotations (different resource type).

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 offers no guidance about when to use this tool versus alternatives. It does not mention that reading_read_submission might be used to read a single batch, nor does it provide any context about typical workflows. Usage must be inferred entirely from the tool name and one-line description.

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 the core behavioral effects: marking a chunk as read and updating last-read progress. But annotations provide no readOnly or destructive hints, and the description does not address idempotency, reversibility, how progress interacts with reading_continue/reading_get_progress, or what happens on repeated calls.

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

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

The description is a single concise sentence with no filler. It front-loads the primary action ('Mark a chunk as read') and then states the additional side effect ('update last-read progress'), earning its place with minimal 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 simple two-parameter tool, the description is minimally adequate. However, it does not explain the relationship between last-read progress and the broader reading workflow, nor does it indicate what the response contains. Since there is no output schema, a bit more context about expected return behavior would help.

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, but it adds no parameter-level detail. bookId and chunkId are self-explanatory names, yet the description never clarifies that chunkId identifies the chunk within the book identified by bookId, or any constraints on these values.

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

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

The description uses a specific verb and resource: 'Mark a chunk as read' and 'update last-read progress.' This clearly identifies a state-change operation and separates it from retrieval tools like reading_read_chunk and progress-query tools like reading_get_progress, even without naming them.

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 usage context is implied: call this after a user finishes reading a chunk to record progress. However, the description gives no explicit when-to-use guidance and does not mention alternatives or situations where another tool should be preferred.

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 readOnlyHint annotation already covers the read-only nature, and the description adds useful behavioral context by stating that the tool returns an image and that the image is intended for Claude to view. It does not contradict the annotation and provides a return expectation beyond what structured metadata offers.

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, front-loaded sentence with no filler. Every part contributes meaning: the action, the target resource, and the output purpose are all covered efficiently.

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 one-parameter read-only tool, the description is largely complete: it identifies the input concept and the output form. It does not describe error cases or card availability, but those are not critical given the tool's simplicity and the presence of a readOnlyHint annotation.

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 provides no description for cardId, and the description only adds the context that the card must be one that has been collected. It does not explain where to obtain cardId or what format it should take, but the single required parameter is simple and reasonably self-explanatory. The description offers minimal additional semantic value.

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

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

The description states a specific verb ('open'), a specific resource ('one collected reading card'), and the output form ('return it as an image for Claude to view'). This clearly distinguishes it from sibling tools like reading_list_cards and reading_collect_card while making the tool's purpose 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 wording 'collected reading card' implies this tool should be used after a card has been collected, but it does not explicitly state when to use this over alternatives or mention any exclusions. The guidance is implied rather than explicit, so it is adequate but not strong.

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

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

The annotations already signal readOnlyHint=true, so no safety ambiguity exists. The description adds useful behavioral detail about returning prevId/nextId, but does not disclose behavior on missing chunks, invalid IDs, or whether the chunk content itself is returned alongside the navigation IDs.

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. It is front-loaded with the action and resource, and the return behavior is stated concisely. It could earn a 5 only if it also communicated usage boundaries or parameter meaning in this space.

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

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

This is a simple two-parameter read operation with readOnlyHint=true and no output schema. The description gives the core behavior and a navigation-related return detail, but omits any mention of error behavior, return content format, or how this tool relates to the nearby list/read 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 description coverage is 0%, and the description does not explain the meaning of bookId or chunkId. The parameter names are suggestive, but the description adds no semantic value beyond the schema's bare string types, and the agent must assume these are the required identifiers.

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 ('Read'), a specific resource ('one book chunk'), and the key return behavior ('return prevId/nextId'). This clearly distinguishes it from siblings like reading_list_chunks, reading_search_chunks, and reading_continue at a glance.

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: call this when you need to read a specific chunk by IDs. However, it provides no explicit when-to-use versus alternatives, no exclusions, and no mention of sibling tools that could serve similar purposes, so the agent must infer selection 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?

The readOnlyHint annotation already signals a safe read operation, and the description does not contradict it. The description adds some useful context by stating the returned content includes 'notes and context,' but it does not disclose further behavioral details such as response shape, pagination, or side effects—though none are expected for a simple read.

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, front-loaded sentence with no filler words. It efficiently communicates the core action and content focus, though it is terse enough that some detail is sacrificed.

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 read tool with a readOnlyHint, the description is minimally adequate: it states what is read and what is included. However, with no output schema and no guidance about where submissionId comes from or what 'context' means, the description leaves notable gaps for an agent that must invoke it correctly.

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

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

With schema description coverage at 0%, the description needed to compensate for the lack of parameter documentation, but it never mentions 'submissionId' or explains how to obtain or format it. The parameter name is self-descriptive and the tool name reinforces the concept, but the description adds little semantic value beyond that.

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

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

The description uses a specific verb ('Read') and resource ('one human note submission batch') and clarifies the payload includes 'notes and context.' It is clear enough to be distinguished from the sibling 'reading_list_submissions' by the singular 'one,' though it does not explicitly name an alternative.

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

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

The phrasing implies this tool is for reading a single submission batch, but it provides no explicit guidance on when to use it versus reading_list_submissions or other related tools. There are no stated exclusions or alternative routing, leaving the agent to infer usage context.

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 carry a title, with no readOnlyHint or destructiveHint. The description implies a mutation ('Attach') but does not disclose whether it creates a new annotation record, modifies the parent, requires special permissions, or has side effects. With no annotation coverage, the description carries the full burden and does not meet it.

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, front-loaded sentence that conveys the core action efficiently. It contains no filler, though it is so terse that it sacrifices important behavioral and parameter 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 an 8-parameter tool with no output schema and no safety annotations, the description is severely incomplete. It does not explain the optional parameters, return value, failure conditions, or how this reply differs from creating an annotation. An agent could call it based on the two required fields but would be guessing about the rest.

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 almost no parameter-level meaning. It hints that parentId refers to an existing annotation and note is likely the reply text, but the eight parameters (kind, mood, tags, quote, bookId, chunkId, parentId, note) are otherwise unexplained. The description fails to compensate for the schema's complete lack of documentation.

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

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

The description uses a specific verb ('Attach') and resource ('Claude reply under an existing user or Claude annotation'). It clearly indicates the tool creates a nested reply to an annotation, and the 'existing' qualifier distinguishes it from sibling tools like reading_annotate_passage that create new top-level annotations.

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 used when an annotation already exists and requires attaching a reply to it. However, it does not explicitly state when to use this tool versus alternatives such as reading_annotate_passage, nor does it mention any exclusions or prerequisites beyond 'existing 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?

With no meaningful annotations beyond the title, the description carries the behavioral burden and does disclose the key side effect: a local image file is written and its absolute path is returned. It also clarifies the 'collected' precondition. It could say more about overwrite behavior, file format, or write permissions, but for a simple rendering action this is solidly transparent.

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 one concise, active-voice sentence that front-loads the action and includes no filler. 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?

For a one-parameter tool with no output schema, the description is functionally complete: it states the input condition, the operation, the artifact produced, and the returned value. Minor details like file format or error behavior are not necessary for correct invocation at this complexity level.

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 provides only a bare string `cardId` with no description, so the description must compensate. It adds the meaningful constraint that the card must already be 'collected' and identifies the target entity as a reading card, but it never explicitly explains how to obtain or format `cardId`. For a single self-named parameter, this is adequate but thin.

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 concrete action ('Render'), a specific resource ('one collected reading card'), and a deliverable ('local image file' and 'absolute path'). This clearly differentiates it from sibling tools like reading_open_card or reading_collect_card, which do not export an image file.

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 correct use case: when you need a local image export of a card that has already been collected. However, it does not explicitly state when to prefer this over alternatives such as reading_open_card or reading_collect_card, nor does it mention any 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 annotation readOnlyHint=true already covers the non-destructive nature of the operation. The description adds no further behavioral disclosure such as result ordering, pagination, matching semantics, or scope of the search, so it contributes little beyond the annotation.

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 clean sentence with no filler, and the main action is front-loaded. It is appropriately short, though a second sentence could add scope details without hurting readability.

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

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

For a simple read-only search with flat parameters, the description plus schema gives a minimally viable picture. But the lack of output schema and absence of details about result format, bookId behavior, and limit semantics leave meaningful gaps for an agent.

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 schema description coverage at 0%, the description must compensate, but it only clarifies that 'query' is a keyword. It says nothing about 'limit' or 'bookId', leaving their meaning and optionality to be inferred from names alone.

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

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

The description uses a clear verb ('Search') and a specific resource ('book chunks') with a keyword mechanism. It distinguishes the tool from list/read siblings by indicating a keyword-based lookup, though it does not clarify whether the search spans all books or is confined to one book.

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

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

The intended use is inferable: call this tool when you need to find chunks by keyword rather than listing or reading chunks. However, it gives no explicit guidance about when to prefer this over siblings like reading_find_passage or reading_list_chunks.

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 a meaningful side effect: notes are marked submitted so they are not sent again. It also reveals the default context-inclusion behavior: each chunk's full text is included once per session. Since the annotations provide no behavioral hints, this is valuable transparency, though it does not cover permission requirements or reversibility.

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 concise sentences with the core purpose front-loaded. Every sentence adds meaningful information, and there is no redundant restating of 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 tool with 8 optional parameters, no output schema, and no parameter descriptions, this description is incomplete. It gives the default behavior but leaves the agent unable to determine how to use context modes, limits, or forced context, and provides no guidance on return values or prerequisites.

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% across 8 parameters, so the description carries the burden of explaining them. It indirectly hints at contextMode via 'include each chunk's full text once per session', but it does not explain bookId, chunkId, sessionId, maxContextChars, contextChunkLimit, forceChunkContext, includeContext, or the other contextMode values.

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

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

The description clearly states a specific action ('Submit open user notes') and the purpose ('for Claude review'). It distinguishes itself from sibling tools like reading_list_submissions and reading_read_submission by emphasizing submission of notes rather than listing or reading them.

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 'open user notes' implies this is for notes not yet submitted, and 'for Claude review' suggests a review context. However, there is no explicit guidance about when to choose this tool over alternatives, nor any exclusions or conditions compared with sibling tools.

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