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

With no annotations provided, the description carries the behavioral disclosure burden. It discloses that fulltext is truncated, capped per item by max_chars_per_item, and that combined response size is intentionally managed. It also reveals that items can span libraries and that each entry's library_id identifies its source. It could mention error behavior or permissions, but the core behavior is 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 dense but mostly efficient. The main action is front-loaded, and the follow-up sentences explain the optional behavior and cross-library capability. A slight restructuring into shorter sentences would improve scannability, but every sentence contributes useful information.

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

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

For a batch metadata/fulltext fetching tool with no output schema, the description covers the essential invocation context: what is fetched, when fulltext is included, how it is truncated, and that items can span libraries. It does not describe the response shape or error handling, but an agent has enough to invoke and interpret the call correctly.

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

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

Schema description coverage is 0%, so the description fully compensates. It explains item_keys (several items), include_fulltext (whether to pull PDF text), and max_chars_per_item (per-item cap to keep response manageable). It also clarifies that when fulltext is off, comparison is on metadata, abstracts, tags, and annotations only.

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

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

The description opens with a specific verb and resource: 'Fetch metadata (and optionally truncated full text) for several items in one call.' It clearly separates this from single-item tools like get_item and get_item_fulltext by emphasizing multi-item batching and comparison/synthesis. The purpose is unmistakable and actionable.

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 clear context for when to use the tool: when you need to compare or synthesize across several items, including across libraries. It also differentiates the two modes (with or without fulltext). However, it does not explicitly state exclusions, such as 'use get_item for a single item' or 'use get_item_fulltext when you need full text for one item.'

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, the description carries the behavioral disclosure burden. It does meaningfully disclose that child content is returned only as a summary, that the tool works across personal and group/shared libraries, and that the response's library_id identifies the owning library. It does not cover error/edge cases or auth, but the read-only nature is clear from the wording.

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 dense sentences front-load the core action and then add return-scope and library-scope details. The parenthetical is slightly long, but every clause contributes behavior or routing value; there is no filler.

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

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

For a one-parameter metadata fetch with no output schema, the description covers what the response contains, what it deliberately omits, how library ownership is conveyed, and which sibling tools to use next. An agent has enough to invoke it correctly and interpret the result.

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

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

The schema provides only the parameter name and type with zero description coverage, so the description must compensate. It adds that the parameter selects exactly one item and that the item may live in any library, with library_id in the response identifying the library. It does not explain the item_key format, but for a single self-describing required parameter this is adequate.

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 ('Get full metadata for one item') and enumerates exactly what is included: bibliographic fields, creators, tags, collections, abstract, and a summary of child notes and attachments. It also distinguishes itself from sibling get_item_fulltext / get_item_notes / get_item_annotations by framing them as next steps rather than the metadata call.

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

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

It clearly implies this tool is for retrieving a single item's metadata rather than listing or searching, and it adds explicit follow-up routing to fulltext/notes/annotations tools. It does not state explicit when-not-to-use conditions or compare against list_items/search_metadata, so it falls just 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?

With no annotations provided, the description carries the full burden. It discloses the output scope (all annotations, reading order) and the value proposition, but it does not mention whether this is a read-only operation, whether it requires specific permissions, whether it can fail (e.g., item has no PDF), or whether it returns an empty list. It is not misleading, but it leaves some behavioral 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 two sentences, front-loads the core action and output, and the second sentence adds a valuable use-case rationale without bloat. 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 a single-parameter read tool with no output schema, the description is quite complete: it lists the output fields, ordering, and the use case. It lacks explicit failure/edge-case behavior (e.g., no PDF, no annotations) and does not name sibling tools, but given the low complexity, it is nearly 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. It explains what item_key refers to implicitly ('an item's PDF') but does not define item_key format, how to obtain it, or any constraints. The description adds context about the item's PDF but the parameter itself is only documented by its name and type. Baseline 3 is appropriate because the single parameter is self-explanatory in 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 uses a specific verb ('Get') and resource ('every PDF annotation on an item's PDF'), enumerates the annotation types (highlights, notes, underlines) and the exact data returned (highlighted text, comment, color, page label, reading order). It clearly distinguishes itself from siblings like get_item_fulltext and get_item_notes by focusing on user annotations rather than raw text or notes.

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

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

The description implies when to use it: when the user's annotations are more useful for synthesis than raw PDF text. It contrasts with raw PDF text, which helps an agent choose between this and get_item_fulltext. However, it does not explicitly name sibling alternatives or state when not to use it, so it falls just short of a 5.

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

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

With no annotations, the description carries the burden and does disclose the on-demand nature, absence of a search-index prerequisite, page-marker format, and truncation behavior with max_chars. It does not cover multi-PDF aggregation or error/permission cases, but the core side effects and result caveats are present.

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

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

Four sentences front-load the core purpose and then layer parameter and behavior details without redundant filler. Each sentence adds value, so it is efficiently structured.

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

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

Despite no annotations and no output schema, the description covers what the tool returns (full text with page markers), how to constrain output, and how truncation is signaled. It is slightly incomplete about the exact shape when an item has multiple PDF attachments and about failure modes, but it is enough for correct 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 descriptions are 0%, so the prose must compensate, and it does: page_start/page_end are documented as 1-indexed and inclusive, max_chars is documented as a cap with a default and truncation cue. item_key is left obvious from the tool name, but all optional parameters receive meaning beyond the schema.

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

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

The description uses a specific action verb ('Extract') and names the exact resource ('an item's PDF attachment(s)'), and it adds page-marker behavior that distinguishes it from metadata/notes/search siblings. An agent can confidently choose this over get_item, get_item_notes, or get_item_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?

It explains when a page range is useful and clarifies that extraction is on-demand and does not depend on the search index, which routes usage away from rebuild_search_index/search_library. It does not explicitly name alternative tools for metadata or notes, but the context is clear enough.

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, the description carries the burden. It discloses that content is converted from HTML to plain text, which is a notable behavioral trait. However, it doesn't specify the return structure, error cases, or whether notes are sorted, leaving some gaps. The conversion detail adds value beyond basics.

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 concise, two sentences, with no fluff. It front-loads the primary function of getting child notes, then clarifies the standalone note case and the conversion behavior. Each sentence adds value, fitting within typical token limits.

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 a single parameter and no output schema, the description covers the essential semantics: what it does, the special case, and a key transformation. It lacks details on return format, but given the simplicity, it is fairly complete. The conversion to plain text is a useful addition.

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

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

Schema description coverage is 0%, meaning the description must explain the item_key parameter. The description does not elaborate on the parameter format or special cases beyond the fact that it can be a standalone note's key. This adds some meaning but is minimal, so a baseline of 3 is 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 clearly states what the tool does: it retrieves notes attached to an item, and also handles standalone notes. It uses a specific verb 'Get' and a clear resource 'item notes'. It distinguishes between two cases, which helps clarify its purpose, though it does not explicitly compare to sibling 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 when to use the tool: when you need notes attached to an item or the content of a standalone note. It does not explicitly state when not to use it or mention alternatives, but the context of retrieving notes is clear, and siblings like get_item_annotations are distinct enough.

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, the description carries the full burden. It discloses aggregation behavior, the meaning of full-text coverage, and the presence of index_last_updated. It does not explicitly state read-only or side-effect-free, but the 'stats' framing makes that reasonably clear. The instruction to surface the timestamp adds useful behavioral context.

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

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

Three sentences, each with distinct value: the stat contents, the parameter behavior, and the user-facing timestamp instruction. Front-loaded with the core purpose. No filler or repetition.

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

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

Given no output schema and no annotations, the description provides enough conceptual detail about return contents (counts, coverage, timestamp, breakdown) and cross-references list_libraries for names. An agent can call the tool and correctly interpret the results.

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

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

Schema coverage is 0%, so the description must compensate. It fully explains the library_id parameter: omitting it yields combined totals across personal and shared libraries with a by_library breakdown, while passing it scopes to one library. This is rich semantic meaning that the bare schema (nullable integer default null) completely lacks.

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 clear, specific noun phrase 'Overall library stats' and enumerates the exact resources involved (items, collections, tags, full-text index coverage). It also ties the coverage to search_library's fulltext/notes scopes, which distinguishes it from sibling tools like list_items or list_collections.

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 concrete parameter guidance: omitting library_id returns combined personal/shared totals with a by_library breakdown, while passing a specific id scopes to one library. It also points to list_libraries for names and explicitly instructs to mention the index_last_updated timestamp. However, it does not explicitly state when NOT to use this tool in favor of a sibling, so it stops short of a 5.

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

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

With no annotations provided, the description carries the behavioral burden, and it does so well: it discloses default aggregation across all libraries, item-count reporting, most-used-first ordering, and the optional library scope. It does not explicitly label the operation as read-only, but 'List tags' plus the aggregate semantics make the behavior clear.

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 action, then efficiently branches into the two parameter modes. Each sentence adds necessary information, and the downstream-use tip is directly relevant, not 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?

Given no annotations and no output schema, the description fully equips an agent to call the tool correctly: parameter behavior, default scope, return details (counts, ordering), and related tool routing are all covered. There is no critical missing 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 fully compensate, and it does. It explains item_key filters to an item's tags, omission triggers global aggregation, and library_id scopes the aggregation to a single library with a pointer to list_libraries. This adds meaningful semantics beyond the bare schema names.

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

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

The description opens with a specific verb and resource ('List tags') and then disambiguates two modes: item-specific tags when item_key is given, and global tag aggregates when omitted. This makes it easy for an agent to understand what get_tags does and to distinguish it from sibling tools like list_items or get_item.

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 each mode and explicitly positions get_tags as a prerequisite for 'discovering the user's own taxonomy before filtering list_items/search_library by tag.' It also names list_libraries for scoping. It stops short of an explicit when-not-to-use statement, but the usage intent is clear.

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

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

With no annotations provided, the description carries the full burden, and it does so well: it discloses the flat-list format, the per-entry fields, that parent_key is null for top-level collections, and the default all-library scope. It does not mention pagination, ordering, or error behavior, but for a simple read-only list tool this is adequate 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 front-loaded with the main purpose, then elegantly packs output fields, default behavior, and a cross-reference into a compact structure. Every sentence earns its place and no detail is redundant.

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 there is no output schema, the description still explains the return entry fields and hierarchy semantics, plus the single parameter. It is complete enough for an agent to call the tool correctly and interpret results. Minor omissions like pagination or result ordering do not materially hurt usability.

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

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

The schema has 0% description coverage, so the description must compensate. It does: it explains that library_id is optional, controls scope, and points to list_libraries for valid values. This adds meaning beyond the bare schema definition of an optional integer/null parameter.

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') with a precisely scoped resource ('every collection (and sub-collection)') and even explains the intended use ('so Claude can build or walk the collection tree'). It also clarifies the output shape with parent links, making it easy to distinguish from list_items and search_library.

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

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

The description explicitly explains the default behavior ('Defaults to every library') and how to narrow it ('pass library_id (see list_libraries) to scope to just one'). It does not name alternatives to exclude, but it does reference list_libraries for valid parameter values, which is strong practical 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?

With no annotations present, the description carries the full burden and does so thoroughly: it discloses sort order ('most recently modified first'), default scope ('every library ... personal plus all group/shared libraries'), exclusions ('not notes/attachments'), and the exact return fields. This goes well beyond the bare schema and gives an agent an accurate behavioral model.

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 dense but every sentence adds necessary information: behavior, ordering, filters, paging, scope, and output shape. It is front-loaded with the core purpose and avoids redundant restatement of the tool name 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?

Despite having no output schema and no annotations, the description gives enough context for correct invocation: it defines the item universe, filter semantics, pagination strategy, library scoping behavior, and return fields. An agent can select and call this tool without needing to inspect sibling tools or make risky assumptions.

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%, but the description compensates by explaining every parameter: tag, limit, offset, item_type, library_id, and collection_key all receive semantic meaning. It also provides concrete examples like 'journalArticle' and tells the agent where to get valid collection_key and library_id 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 opens with a specific verb and resource: 'List items ... in the library', and immediately clarifies scope by excluding notes/attachments and defining item categories. It also distinguishes itself from siblings like get_item and search_metadata by describing the list behavior and return fields.

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

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

It explicitly explains when to use filters, how to page with limit/offset, and how to scope to a specific library via library_id. It also references sibling tools list_collections and list_libraries as sources for parameter values, giving clear routing guidance.

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

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

With no annotations, the description must disclose behavioral traits. It does not explicitly state that the tool is read-only or non-destructive, but the nature of listing is inherently read-only. It does not mention potential side effects or limitations, but the absence of parameters and side effects allows a 4.

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-organized and front-loaded with the core purpose. It is four sentences, but each adds essential context about usage with siblings. It could be slightly more concise, but 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?

The tool has no parameters, no output schema, and no annotations, so the description is the only source of information. It fully explains what the tool does, what it returns, and how to use the result with other tools. Nothing essential is missing.

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

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

The tool has zero parameters, and the description clearly explains the output (library_id, name, type) which is the primary useful information. Schema coverage is 100% but with no parameters, the description adds meaning by explaining what the returned data contains.

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

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

The description clearly states the tool lists all Zotero libraries visible to the server, including personal and group libraries, and specifies what it returns (library_id, name, type). It distinguishes itself from sibling tools by explaining how library_id is used by other 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 provides explicit usage guidance: it explains when to use this tool (to discover library IDs) and how to use the result with other tools. It also clarifies that item-level tools don't need library scoping, preventing misuse.

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, the description carries the full burden and does so thoroughly. It discloses incremental-by-default behavior, the full=True wipe-and-rebuild mode, cross-library indexing, and the practical tradeoff about progress output for large libraries.

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 tool's core purpose and is dense with useful behavior, usage, and parameter guidance. Every sentence contributes actionable information without filler.

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

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

For a complex operation with no output schema and no annotations, the description is remarkably complete. It covers default behavior, parameter effects, performance characteristics, and when an alternative approach is preferable, leaving little ambiguity for an agent deciding how to invoke it.

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

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

Schema description coverage is 0%, so the description must explain the parameters itself. It explains both parameters: library_id scopes indexing to a single library and references list_libraries, while full controls incremental versus full rebuild. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states the specific action—rebuilding the full-text search index—and connects it to the exact scopes ('fulltext' and 'notes') of the sibling search_library tool. This makes the tool's role unmistakable and distinguishes it from other 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 provides explicit when-to-use guidance: it is best for small incremental top-ups within a conversation, and for large libraries it recommends running 'python scripts/build_index.py' in a terminal instead. It also clarifies when to use library_id versus the default all-libraries behavior.

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 it does so thoroughly. It discloses that fulltext/notes rely on a separately built index rather than live queries, that results include index_last_updated, and that the agent must surface that timestamp to users. This exceeds what annotations would typically provide.

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 dense but every sentence adds necessary operational context. It front-loads the core purpose, then structures scope, library scoping, result shape, and the index freshness caveat in a logical order.

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

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

Given no output schema, the description still conveys what results contain, how to fetch more details, when to expect live versus indexed data, and what to tell the user about freshness. An agent has enough context to invoke the tool correctly and interpret its output.

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 thoroughly explains scope values and library_id behavior, and it implies query semantics through the overall search purpose. It does not elaborate on limit, but the schema title and default make it self-explanatory.

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

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

States a specific verb and resource: 'Search across the whole library', and clarifies the operation by enumerating the four scope modes. It distinguishes itself from siblings by covering metadata, fulltext, notes, and all-library scope rather than a simple metadata or item listing.

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

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

Gives clear context for when to use the tool: use it for cross-library search, pass library_id to narrow to one library, and use rebuild_search_index when fulltext/notes are unavailable. It does not explicitly say 'use search_metadata instead for metadata-only queries', but it does explain the metadata scope and points to related tools for fetching results.

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, the description carries the burden and discloses important behavioral traits: it is fast, searches personal plus all group/shared libraries by default, and deliberately excludes PDFs and notes. It doesn't describe return shape or match semantics, but the key scope and limitation boundaries are clear.

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 sentences with no filler: each sentence adds necessary scope, exclusions, alternatives, or invocation guidance. The most important limitation is front-loaded with 'does NOT search inside PDFs or notes.'

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 search tool with no output schema and no annotations, the description covers the main operational needs: search fields, default scope, scoping parameter, and alternatives. It omits a few details like limit semantics and result-return expectations, but nothing critical blocks correct 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%, but the description compensates by defining the query semantics (titles, abstracts, creator names) and explaining library_id (scope to one library, see list_libraries). The limit parameter is not described in prose, though its schema default is visible.

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

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

States a specific verb and resource: 'search over item titles, abstracts, and creator names.' It also explicitly distinguishes itself from full-text search, so an agent can tell what this tool does and does not cover.

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

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

Gives explicit when-to-use guidance ('quickly locating an item you already know roughly') and clear alternatives for content search. Minor deduction because it names 'search_fulltext', which is not present in the sibling list, making the alternative routing slightly unreliable.

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