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

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation ('Create a new highlight') and mentions the return value, but lacks details on permissions, side effects, error conditions, or rate limits. For a mutation tool with zero annotation coverage, this is insufficient.

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

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

The description is well-structured and front-loaded with the core purpose. Each sentence adds value: the first states the action, the second covers required parameters, the third optional ones, and the fourth the return. It's efficient with minimal waste, though slightly verbose for such a simple tool.

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

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

Given a mutation tool with no annotations, 0% schema coverage, but an output schema exists, the description is moderately complete. It covers parameters and return value, but lacks behavioral context (e.g., auth needs, error handling). The output schema reduces the need to explain returns, but more guidance is needed for safe use.

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

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

Schema description coverage is 0%, so the description must compensate. It effectively explains all 4 parameters: 'text' and 'book_id' as required, and 'note' and 'tags' as optional. This adds crucial meaning beyond the bare schema, though it doesn't specify formats or constraints (e.g., text length, tag structure).

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 ('Create a new highlight') and resource ('on a book'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'tag_highlight' or 'update_highlight', which also involve highlight manipulation, so it doesn't reach the highest score.

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 like 'tag_highlight' or 'update_highlight'. It mentions required and optional parameters but doesn't specify use cases, prerequisites, or exclusions, leaving the agent to infer usage from context 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool returns the created tag with ID and name, which is helpful, but fails to address critical aspects like whether this is a mutating operation (implied by 'Create'), potential side effects, error conditions, or rate limits. This leaves significant gaps in understanding the tool's 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 extremely concise with two sentences that are front-loaded and waste no words. The first sentence states the core action, and the second adds useful return information, making it efficient and well-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 the tool's moderate complexity (a creation operation with one parameter) and the presence of an output schema (which handles return values), the description is minimally adequate. However, it lacks details on usage context, parameter meaning, and behavioral traits, making it incomplete for safe and effective use without additional inference.

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

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

The input schema has 0% description coverage, so the description must compensate. It does not mention the 'name' parameter at all, leaving its purpose and constraints undocumented. However, with only one parameter and an output schema present, the baseline is 3, as the description adds minimal value beyond the schema.

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

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

The description clearly states the action ('Create a new tag') and resource ('tag'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'list_tags' or 'delete_tag' in terms of when to use each, which prevents a perfect score.

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 like 'list_tags' or 'delete_tag', nor does it mention prerequisites such as authentication or permissions needed for creation. It simply states what the tool does without contextual usage instructions.

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 provided, the description carries the full burden of behavioral disclosure. It states the tool deletes a highlight and returns a confirmation, which covers the basic operation. However, it lacks critical details like whether deletion is permanent/reversible, permission requirements, error handling (e.g., invalid ID), or side effects (e.g., impact on tagged highlights). For a destructive tool with zero annotation coverage, this is insufficient.

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 and front-loaded: the first sentence states the core purpose, and the second adds return value information. Every sentence earns its place with no wasted words, 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?

Given the tool's destructive nature, no annotations, and a simple input schema, the description is minimally adequate. It covers the basic operation and return confirmation, and the presence of an output schema means return values don't need explanation. However, for a deletion tool, it should ideally include more behavioral warnings or prerequisites to be fully complete.

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

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

The description adds meaningful context for the single parameter by specifying it's an ID used to identify the highlight to delete. With 0% schema description coverage (the schema only defines 'highlight_id' as an integer with no description), this compensates well by clarifying the parameter's purpose. However, it doesn't detail ID format or sourcing (e.g., from 'list_highlights').

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 ('Delete') and resource ('a highlight by ID'), making the purpose immediately understandable. It distinguishes itself from siblings like 'delete_tag' by specifying the resource type. However, it doesn't explicitly differentiate from other destructive operations like 'update_highlight' that might also modify highlights.

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. It doesn't mention prerequisites (e.g., needing an existing highlight ID), exclusions, or compare it to siblings like 'update_highlight' or 'delete_tag'. The agent must infer usage 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?

No annotations are provided, so the description carries the full burden. It states the tool deletes a tag and returns a confirmation, which implies a destructive mutation. However, it lacks critical behavioral details: whether deletion is permanent, what permissions are required, if there are side effects (e.g., on tagged highlights), or error handling for invalid IDs. This is inadequate for a destructive 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 description is extremely concise with two sentences: the first states the purpose, and the second describes the return value. Every word earns its place, and it's front-loaded with the core action. No wasted text.

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

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

Given the tool's complexity (destructive mutation with 1 parameter), lack of annotations, and an output schema (which covers return values), the description is minimally adequate. It states the action and return, but misses key context like prerequisites, side effects, and error cases, leaving gaps for safe 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?

Schema description coverage is 0%, so the description must compensate. It mentions 'tag_id' as the parameter, adding meaning beyond the bare schema. However, it doesn't explain what a tag ID is (e.g., from 'list_tags'), its format, or validation rules. This provides basic but incomplete semantic 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 ('Delete') and the resource ('a tag by ID'), which is specific and unambiguous. However, it doesn't explicitly differentiate this tool from sibling tools like 'delete_highlight' or 'list_tags', which would be needed for a perfect score.

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. It doesn't mention prerequisites (e.g., the tag must exist), when not to use it, or how it relates to siblings like 'list_tags' (to check IDs) or 'create_tag' (for 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?

With no annotations provided, the description carries the full burden and does well by disclosing key behaviors: pagination support via cursor, inclusion of book metadata in results, and the tool's nature as an export endpoint for bulk operations. It doesn't cover all possible behaviors like rate limits or auth needs, but provides substantial 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 front-loaded with the core purpose, followed by usage details and alternatives in three concise sentences. Every sentence adds value without redundancy, making it efficient and well-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 the tool's complexity (bulk export with pagination), no annotations, and an output schema present, the description is largely complete. It covers purpose, usage, key behaviors, and parameter semantics, though it could add more on error handling or response structure beyond metadata mention.

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 explains the purpose of parameters: filtering by date ('updated_after' implied) or specific books ('book_ids'), and pagination via cursor. However, it doesn't detail parameter formats or constraints, leaving some gaps.

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 specific action ('bulk export highlights') and resource ('highlights'), distinguishing it from siblings like search_highlights or list_highlights by emphasizing bulk data retrieval. It explicitly mentions filtering capabilities by date or books, adding specificity.

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 explicit guidance on when to use this tool ('for bulk data retrieval') and when not to ('not for interactive queries'), naming alternatives like search_highlights and list_highlights for interactive use. This clearly differentiates it from sibling 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns full metadata, which is helpful, but lacks critical details like whether this is a read-only operation, potential error conditions (e.g., invalid ID), authentication requirements, or rate limits. For a retrieval tool with zero annotation coverage, this leaves significant gaps.

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

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

The description is highly concise and well-structured, with two sentences that efficiently convey the core functionality and return data. Every sentence adds value without redundancy, making it easy to parse and understand 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?

Given the tool's low complexity (single parameter, no nested objects) and the presence of an output schema, the description is reasonably complete. It covers the purpose and return metadata adequately. However, it lacks usage guidelines and behavioral details, which are minor gaps in an otherwise solid 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?

The input schema has 0% description coverage, but the description compensates by specifying that the single parameter 'book_id' is used to get a book by ID. This adds meaningful context beyond the schema's type information. However, it doesn't detail format constraints or examples, preventing a perfect score.

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

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

The description clearly states the tool's purpose with a specific verb ('Get') and resource ('a single book/source by ID'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from its sibling 'list_books' beyond the singular vs. plural distinction, which keeps it from a perfect score.

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 like 'list_books' or 'get_document'. It mentions retrieving by ID but doesn't clarify prerequisites, such as needing a valid book ID from another operation, or when to choose this over other retrieval 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?

With no annotations provided, the description carries the full burden. It discloses that the tool returns 'complete document' with listed fields, which is useful behavioral context. However, it lacks details on error handling, permissions, or rate limits, leaving gaps for a read 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 description is front-loaded with the core purpose in the first sentence, followed by a concise list of returned fields. Every sentence adds value without redundancy, making it efficient and well-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 the tool's low complexity (1 parameter) and the presence of an output schema, the description is largely complete. It covers purpose and return fields adequately, though it could benefit from more behavioral details like error cases 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?

The description adds meaning by clarifying that 'document_id' is used to retrieve a 'single Reader document', which is not evident from the schema alone (0% coverage). It compensates well for the low schema coverage, though it doesn't specify ID format 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 specific action ('Get a single Reader document by ID') and resource ('Reader document'), distinguishing it from siblings like 'list_documents' (which retrieves multiple) and 'get_book' (which targets a different resource). It precisely defines the scope with 'with full content'.

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 by specifying 'by ID' and 'full content', suggesting it's for retrieving a specific document's details rather than listing or filtering. However, it does not explicitly state when to use alternatives like 'list_documents' or 'get_book', missing explicit exclusions or comparisons.

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 provided, the description carries the full burden. It discloses that the tool returns data (not a mutation) and specifies the return fields (text, note, tags, book title, author, URL), which is useful behavioral context. However, it doesn't mention error handling, permissions, or rate limits, leaving gaps for a read 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 description is front-loaded with the core purpose in the first sentence and details return values in the second. Every sentence earns its place with no wasted words, making it highly efficient and well-structured for quick 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?

Given 1 parameter, no annotations, and an output schema (which handles return values), the description is mostly complete: it states the purpose, usage context, and key return fields. However, it lacks error cases or behavioral nuances (e.g., what happens if the ID doesn't exist), leaving minor gaps in 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 input schema has 1 parameter with 0% description coverage, but the description compensates by clarifying that 'highlight_id' is used to 'Get a single highlight by ID'. This adds meaning beyond the bare schema, though it doesn't detail format constraints (e.g., integer range). Since there's only 1 parameter, the baseline is high.

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 specific action ('Get a single highlight by ID') and resource ('highlight'), distinguishing it from siblings like 'list_highlights' (which returns multiple) and 'search_highlights' (which filters by criteria). It explicitly includes 'book metadata included' to differentiate from potentially simpler retrieval tools.

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

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

The description implies usage when needing a specific highlight by its ID, with context from 'single highlight by ID' suggesting it's for detailed retrieval rather than listing or searching. However, it doesn't explicitly state when not to use it (e.g., vs. 'list_highlights' for multiple items) or name alternatives, keeping it from a perfect score.

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 provided, the description carries the full burden. It discloses that filtering is optional and gives examples of filter usage, but it doesn't mention behavioral traits like pagination (implied by 'page' and 'limit' parameters), rate limits, authentication needs, or what the output contains. It adds some context but leaves gaps.

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

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

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by specific parameter guidance. Every sentence earns its place by providing essential information without redundancy or fluff.

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 parameters with 0% schema coverage and no annotations, the description is incomplete—it only explains 3 parameters. An output schema exists, so return values needn't be described, but for a list tool with filtering, more parameter guidance would help. It's adequate but has clear 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. It adds meaning for 3 parameters: 'category' (lists acceptable values), 'num_highlights_gte' (explains filtering purpose), and 'updated_after' (specifies ISO 8601 format). However, it doesn't cover 'source', 'page', or 'limit', leaving them undocumented. The value added is significant but incomplete.

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: 'List books and sources with optional filtering.' It specifies the verb ('List') and resource ('books and sources'), though it doesn't explicitly differentiate from sibling tools like 'list_documents' or 'list_highlights' beyond the resource name.

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

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

The description implies usage through parameter explanations (e.g., 'Use num_highlights_gte to filter...'), but it doesn't explicitly state when to use this tool versus alternatives like 'list_documents' or 'search_highlights'. It provides context for filtering but lacks 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?

With no annotations provided, the description carries full burden. It mentions filtering capabilities but doesn't disclose important behavioral traits like pagination behavior (implied by page/limit parameters but not explained), rate limits, authentication requirements, or what the output contains. The description adds some context about filter values but misses key operational 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?

Three concise sentences with zero waste. The first states the purpose, the next two explain parameter semantics. It's appropriately sized and front-loaded with the core functionality. Could potentially integrate pagination mention for perfect 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?

Given 5 parameters with 0% schema coverage and no annotations, the description does well on parameter semantics but misses behavioral context. The existence of an output schema reduces the need to describe return values, but for a list operation with pagination and filtering, more guidance on usage patterns and limitations would be beneficial.

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 fully. It successfully explains the semantics of all three filter parameters (location, category, updated_after) by detailing acceptable values and formats. While it doesn't mention page and limit parameters, these are self-explanatory pagination controls, and the description covers the more complex filter semantics that would otherwise be undocumented.

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 'List' and resource 'documents in Readwise Reader' with the scope of optional filters. It distinguishes from siblings like get_document (singular) and list_books/highlights/tags (different resources), but doesn't explicitly contrast with search_highlights which might overlap in functionality.

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 search_highlights or get_document. The description mentions optional filters but doesn't provide context about typical use cases or when other tools might 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?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it returns paginated results (highlights plus total count and next_page) and supports filtering. However, it doesn't cover permissions, rate limits, error conditions, or whether it's read-only (though 'list' implies safe). The description doesn't contradict annotations, as none exist.

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

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

The description is well-structured and front-loaded with the core purpose, followed by specific usage notes and return details. Every sentence adds value: the first states purpose, the second provides a concrete example for a parameter, and the third explains the return format. 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?

Given the tool's moderate complexity (5 parameters, filtering, pagination) and no annotations, the description does a good job covering key aspects: purpose, parameter usage example, and return structure. With an output schema present, it doesn't need to detail return values. However, it could better address sibling differentiation and behavioral constraints like rate limits.

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 adds meaningful context for 'updated_after' (ISO 8601 date string with examples) and mentions filtering by 'book' and 'tag,' which map to 'book_id' and 'tag' parameters. It also implies pagination via 'page' and 'limit' through the return structure, though not explicitly naming them. This partially compensates 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?

The description clearly states the tool's purpose as 'List highlights with optional filtering by book, tag, or recency,' which specifies the verb (list) and resource (highlights). It distinguishes from siblings like 'get_highlight' (singular) and 'search_highlights' (likely full-text search), but doesn't explicitly differentiate from 'list_books' or 'list_tags' which list different resources.

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 through the mention of filtering options (book, tag, recency) and pagination, suggesting it's for retrieving multiple highlights. However, it doesn't explicitly state when to use this vs. alternatives like 'search_highlights' or 'get_highlight,' nor does it mention prerequisites or 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?

With no annotations provided, the description carries the full burden and adds valuable behavioral context: it specifies the return format ('every tag with its ID and name') and a key operational trait ('No pagination needed — tag collections are typically small'). This discloses practical usage details beyond basic functionality.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by essential behavioral details in the second. Both sentences earn their place by providing critical information without any waste or redundancy.

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

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

Given the tool's simplicity (0 parameters, no annotations, but with an output schema), the description is complete: it explains what the tool does, what it returns, and a key behavioral trait (no pagination). The output schema likely covers return values, so the description need not detail them further.

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 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately focuses on behavior and output, not parameters, earning a baseline score of 4 for not adding unnecessary param info.

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 specific action ('List all tags') and resource ('in your Readwise library'), distinguishing it from siblings like 'create_tag', 'delete_tag', or 'tag_highlight'. It precisely defines the scope and operation without 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?

The description implies usage for retrieving all tags, but does not explicitly state when to use this tool versus alternatives like 'search_highlights' or 'list_highlights' that might involve tags. It provides clear context for tag retrieval but lacks explicit exclusions or comparisons to sibling 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?

With no annotations provided, the description carries the full burden. It discloses that the service 'fetches and parses the article automatically,' which is useful behavioral context. However, it lacks details on permissions, rate limits, error handling, or what the output contains (though an output schema exists). The description doesn't contradict any 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 front-loaded with the core purpose, followed by key constraints and parameter details. Every sentence adds value: the first states the action, the second explains automation and URL constraints, and the third clarifies the location parameter. No wasted words or redundancy.

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

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

Given the tool's moderate complexity (5 parameters, 1 required) and the presence of an output schema (which handles return values), the description is largely complete. It covers the primary function, key constraints, and the most critical parameter. However, it lacks details on optional parameters (title, tags, notes) and behavioral aspects like error cases.

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

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

Schema description coverage is 0%, so the description must compensate. It explains the 'location' parameter's purpose, enum values, and default, adding meaningful semantics beyond the schema. However, it does not cover the other four parameters (url, title, tags, notes), leaving gaps in understanding their roles and formats.

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 specific action ('Save a URL') and target resource ('to Readwise Reader'), distinguishing it from sibling tools that handle highlights, tags, books, and documents. It explicitly positions this as 'the primary way to add content to Reader,' making its 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 description provides clear context for when to use this tool ('the primary way to add content to Reader') and mentions constraints ('Only http:// and https:// URLs are accepted'). However, it does not explicitly state when not to use it or name alternatives among the sibling tools (e.g., for non-URL content).

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 provided, the description carries full burden. It explains the search behavior (three search types) and return format (highlights with book title, author, URL). However, it doesn't mention pagination, rate limits, authentication needs, or error conditions that would be important for a search 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 efficiently structured with two paragraphs: first explains the search methods, second provides usage guidelines with examples. Every sentence adds value with no wasted words, and key information is front-loaded.

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

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

Given 5 parameters with 0% schema coverage and no annotations, the description does well explaining the search_type parameter and return format. Since an output schema exists, it doesn't need to detail return values. However, it leaves most parameters unexplained and doesn't cover behavioral aspects like error handling or performance characteristics.

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 explains the 'search_type' parameter thoroughly with examples for each enum value, adding significant meaning beyond the bare schema. However, it doesn't explain 'query', 'book_id', 'tags', or 'limit' parameters, leaving 4 of 5 parameters without semantic 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 tool searches highlights using three specific search methods (semantic, full-text, or hybrid). It distinguishes from siblings like 'list_highlights' by specifying search functionality rather than simple listing, and from 'get_highlight' by being a search rather than retrieval by ID.

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 explicit guidance on when to use each search_type: 'semantic' for concept queries, 'fulltext' for exact phrase matching, and 'hybrid' as default when unsure. This gives clear alternatives within the tool itself, though it doesn't compare to sibling 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?

With no annotations provided, the description carries full burden and does well: it discloses the mutation behavior (add/remove), the side effect of tag creation when adding, and the return value format. However, it doesn't mention error conditions (e.g., what happens if highlight_id doesn't exist), permission requirements, or rate limits, leaving some behavioral aspects uncovered.

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 perfectly front-loaded with the core purpose in the first sentence, followed by specific usage instructions and return value information. Every sentence earns its place with no wasted words, making it highly efficient and scannable.

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 a mutation tool with 3 parameters (0% schema coverage), no annotations, but with an output schema, the description is nearly complete: it covers purpose, usage, parameter semantics, and return format. The output schema likely handles return value details, so the description appropriately focuses on behavior. Minor gaps remain in error handling and permissions.

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 fully, which it does excellently: it explains the meaning of the 'action' parameter with enum values ('add' vs 'remove'), clarifies that 'tag' refers to a tag name (with creation behavior), and implies 'highlight_id' identifies the target highlight. This adds crucial semantic context 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 specific action ('Add or remove a tag on a highlight') with the exact resource ('highlight'), distinguishing it from siblings like create_tag or delete_tag which handle tags independently. It precisely defines the tool's scope without 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?

The description provides explicit guidance on when to use each action ('Use action='add' to tag a highlight... Use action='remove' to untag it'), including the behavioral consequence ('creates the tag if it doesn't exist'). It clearly differentiates this from sibling tools like create_tag (which creates tags independently) or update_highlight (which modifies highlight content).

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 provided, the description carries the full burden of behavioral disclosure. It usefully states that 'Only the provided fields are updated' (partial update behavior) and 'Returns the full updated highlight' (output behavior), which are valuable beyond basic mutation. However, it doesn't cover important aspects like authentication needs, error conditions, rate limits, or whether the operation is idempotent/reversible.

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 perfectly concise with two sentences that each earn their place. The first sentence states the core purpose, and the second adds important behavioral details about partial updates and return values. There's zero wasted language, and information is front-loaded appropriately.

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 this is a mutation tool with no annotations, 3 parameters, 0% schema coverage, but with an output schema, the description does reasonably well. It covers the partial update behavior and return value, and the output schema will handle return format details. However, for a mutation tool, it should ideally mention permission requirements or side effects that aren't covered by the structured data.

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 description coverage is 0%, so the description must compensate. It meaningfully explains that parameters 'text' and 'note' correspond to updatable fields of a highlight, and that 'highlight_id' identifies which highlight to update. This adds crucial semantic context beyond the bare schema types. However, it doesn't clarify the meaning of null values for text/note (whether they clear the field or leave unchanged).

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 ('Update') and resource ('an existing highlight's text or note'), making the purpose immediately understandable. It distinguishes this from sibling tools like 'create_highlight' or 'delete_highlight' by specifying it's for modifying existing highlights rather than creating or deleting them. However, it doesn't explicitly differentiate from 'update_progress' which might be a related but different operation.

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. It doesn't mention prerequisites (e.g., needing an existing highlight ID), when not to use it (e.g., for creating new highlights), or direct alternatives among the sibling tools. The agent must infer usage from the tool name and description alone without explicit 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is an update operation (implying mutation) and describes the return value, but doesn't mention permission requirements, rate limits, or whether the operation is reversible. The description adds some behavioral context but leaves important aspects 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?

The description is extremely concise with just two sentences that each earn their place: the first states the purpose, the second explains the parameter semantics and return value. No wasted words, perfectly front-loaded with the core functionality.

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 an output schema (so return values don't need explanation in the description) and relatively simple parameters, the description covers the essential aspects well. It explains the parameter semantics that aren't in the schema and states what the tool returns. For a 2-parameter update tool with output schema, this is reasonably 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?

With 0% schema description coverage, the description must compensate for the lack of parameter documentation. It provides crucial semantic information about reading_progress being 'a float from 0.0 (unread) to 1.0 (finished)', which explains the numeric range constraints that are only hinted at in the schema's min/max values. However, it doesn't explain document_id's purpose or format.

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 specific action ('Update the reading progress') and resource ('for a Reader document'), distinguishing it from sibling tools like update_highlight which handles different document aspects. It provides precise scope about what aspect of the document is being modified.

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 by specifying it's for updating reading progress on documents, but doesn't explicitly state when to use this versus alternatives like update_highlight or other document-related tools. No explicit exclusions or prerequisites are mentioned.

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