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

Annotations already signal a non-destructive, idempotent write (readOnly=false, destructiveHint=false, idempotentHint=true), so the bar is lower. The description adds concrete behavioral detail: adding to a collection does not remove the item from other collections. It does not mention error cases or duplicate handling, but that is minor given the annotation coverage. No contradiction.

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

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

Two short, purposeful sentences. The action is front-loaded in the first sentence, and the second adds a meaningful use case without redundancy. Every word earns its place.

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

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

For a simple two-key operation with an output schema present and annotations covering safety and idempotency, the description provides the essential semantic and scenario details. It lacks explicit guidance on key sources or edge cases, but the simplicity of the tool and the annotation coverage make this a minor gap rather than a blocking one.

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

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

Schema description coverage is 0%, so the description must compensate. It does identify item_key as referring to an existing Zotero item and collection_key as referring to a collection, but it does not explain key format, provenance, or any constraints. This is partial compensation only; the agent still has to infer key details from naming and domain knowledge.

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 'Add' and identifies both operands: an existing Zotero item and a collection. It explicitly contrasts with moving by stating 'without moving it from other collections', which distinguishes it from sibling tools like create_item or batch_organize. An agent can immediately understand what this tool does.

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?

'Use this to organize a paper into a folder' provides a clear, explicit use case, and 'without moving it from other collections' clarifies the boundary of the operation. It does not explicitly name alternative tools or state hard when-not-to-use conditions, but the context is strong enough for an agent to decide when to invoke it.

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

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

Beyond the annotations, the description discloses meaningful side effects: it can auto-download a PDF via Unpaywall/PMC/bioRxiv or accept a local file path. This is useful external-behavior context. It stops short of detailing failure or duplicate behavior, but annotations already signal mutating and non-idempotent behavior.

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

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

The description is two sentences with no filler. It front-loads the core action, then explains usage modes, then gives an explicit trigger. 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 relatively simple tool with an output schema, the description covers the main input modes and use case well. The only notable omission is guidance on what happens if both doi and pdf_path are supplied, but that is a minor gap given the rest of the definition.

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% property description coverage, so the description must help interpret parameters. It maps doi to the auto-download capability and pdf_path to the local-file option, but it never explicitly refers to parent_key or explains the relationship or precedence of doi vs pdf_path. Property names help, but the description only 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 opens with a specific verb and resource: 'Attach a PDF to a Zotero item.' It clearly distinguishes this from read-only sibling tools like get_item_attachments by focusing on adding an attachment, and it further clarifies the two input modes (auto-download vs local file path).

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 an explicit trigger: 'Use this when the user wants to add a PDF to a paper that doesn't have one.' This is a clear usage context, though it does not explicitly name alternative tools or state when not to use it.

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

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

Annotations already declare read-only and idempotent behavior, and the description reinforces this by stating it 'Reads ~/Zotero/zotero.sqlite read-only.' It also adds valuable context: the exact error messages that occur, the environment variable override, and the nature of the returned summary. This goes well beyond the 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 dense but every sentence carries distinct value: problem, symptoms, trigger conditions, file path, override mechanism, and return type. It is longer than a one-liner but that length is justified by the diagnostic context.

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

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

The description covers what, when, where, and what is returned, and the output schema exists to handle return-value details. The only notable gap is the undocumented 'include_items' parameter, which prevents the description from being fully complete for 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?

The schema coverage is 0% and the description does not explain the meaning of the only parameter, 'include_items.' Although the parameter name hints at whether item keys are included, the description never connects it to the audit scope. For a low-coverage schema, the description should compensate, and it does not.

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

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

The description names a specific verb ('Audit'), a specific resource ('local Zotero SQLite database'), and a precise diagnostic purpose (finding keys with forbidden characters). It clearly differentiates this tool from sibling search/get operations by focusing on key validation rather than retrieval or mutation.

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

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

The description explicitly states when to use the tool: 'when the user reports sync errors' or 'proactively after any bulk library operation.' It does not explicitly name alternatives or exclusion criteria, but the context is clear enough that an agent can decide when this diagnostic is 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?

The description adds useful behavioral context by stating that the tool handles rate limiting and version conflicts, information not present in the annotations. It does not explain the conflict-resolution mechanism, but given that readOnlyHint and destructiveHint already cover the mutability profile, this is sufficient extra 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 three short sentences with the core operation front-loaded. The usage example and the rate-limit/version-conflict note each add value without 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 a simple three-parameter schema, existing annotations, and an output schema, the description covers the essential purpose, usage context, and key runtime behaviors. Minor gaps remain around version-conflict outcomes and parameter format details, but they do not prevent an agent from selecting and invoking the tool correctly.

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

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

With 0% schema description coverage, the description provides the only semantic mapping for the parameters: tags are added, item_keys identify the multiple items, and collection_key is the destination collection. The 'and/or' wording implies optionality, but it does not clarify the accepted string/array/null forms or the exact relationship between the fields.

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/resource combination: adding tags and/or moving multiple items to a collection in one operation. The 'multiple items' and 'one operation' phrasing distinguishes this bulk tool from single-item siblings like add_to_collection and manage_tags, even without naming them.

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

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

'Use this for bulk organization' is an explicit when-to-use directive, reinforced with concrete examples such as tagging search results and grouping papers into a collection. It does not state when not to use it or explicitly name a single-item alternative, so it misses the top 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?

The description adds behavioral context beyond the annotations by explaining that the tool auto-detects full build vs incremental sync, that 'both' runs graph then fulltext in sequence, and that full_rebuild forces a complete rebuild. It does not overpromise safety, consistent with readOnlyHint=false and destructiveHint=false.

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

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

The description is compact, front-loaded with the core purpose, and each sentence carries distinct useful information. The type breakdown and rebuild guidance are structured clearly without 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?

The description covers the main decision points: which type to choose, when to use the tool, and how to force a rebuild. The presence of an output schema covers return-value expectations. The only notable completeness gap is the undocumented 'limit' parameter.

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 carry parameter meaning. It does a good job explaining 'type' values and 'full_rebuild', but it never explains the 'limit' parameter, which remains undocumented in both schema and description. This is a real gap for an agent deciding how to parameterize the call.

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

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

The description clearly states the verb 'Build or update' and the resource 'indexes for your Zotero library'. It also enumerates the specific index types and what each enables, making the tool's role unambiguous relative to the 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 explicitly says when to use it: 'after adding new papers to enable graph queries and full-text search.' It also distinguishes the effects of each type option, but does not explicitly state when not to use it or which sibling might be an alternative, though no direct alternative exists among siblings.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds useful context by naming the external sources (CrossRef and OpenAlex), the reported fields, and the fact that it checks whether the published version is already in the library. No contradictions with annotations.

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

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

Three sentences, each earning its place: purpose, usage context, and output/source details. The most important information is front-loaded and there is no unnecessary 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 the annotations cover safety and an output schema exists, the description sufficiently covers behavior and inputs for a check-like tool. The main minor gap is the lack of explicit item_keys semantics, but overall the agent has enough context to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explicitly explain that item_keys refers to the preprint item keys to check, nor does it clarify the accepted formats beyond what the schema already shows. The usage context implies the meaning but the description adds little parameter-level value.

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

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

The description uses a specific verb ('Check') and resource ('preprints') and clearly states the outcome: determining if a final journal version exists and reporting DOI, journal name, and library presence. It is distinct from siblings like check_retractions by focusing on publication status rather than retractions.

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 provides an explicit use case: when the user has bioRxiv/medRxiv/arXiv papers and wants to know if a final journal version exists. It does not explicitly name alternatives or exclusions, but the context is clear enough to guide tool selection.

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

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

Annotations already carry the safety profile (readOnly=true, openWorldHint=true, idempotentHint=true, destructiveHint=false). The description adds behavioral context beyond that: which external services are consulted and their reliability ('Uses CrossRef (authoritative) and OpenAlex'), which informs how much an agent should trust the result. No contradiction with annotations.

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

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

Four short sentences, each carrying distinct value: purpose, data sources, usage triggers, and parameter format. It is front-loaded with the core purpose and contains zero filler or repetition of information already in the schema or annotations.

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

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

For a single-parameter, read-only check tool with a present output schema and four rich annotations, the description covers purpose, sources, when-to-use, and parameter cardinality. The only gap is the undefined item_keys domain concept, which is minor given the schema and output schema handle the mechanics.

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. 'Accepts one or more item keys' clarifies the otherwise ambiguous anyOf string-or-array schema and confirms batch multiplicity. However, it never defines what an item key is or where to obtain one, leaving part of the burden unmet.

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: 'Check whether papers have been retracted or corrected.' It goes further by naming the data sources (CrossRef, OpenAlex), and the retraction-checking purpose is unique among the 40+ sibling tools, so an agent can distinguish it without opening the schema.

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

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

Provides explicit trigger conditions: 'when the user asks about paper validity, before citing papers, or as part of a literature audit.' These are concrete, actionable contexts. It lacks when-not-to-use guidance or named alternatives, but the stated triggers are clear enough to route an agent correctly.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses detailed behavior: what it returns, that it performs live probes, that it flags env-var overrides pointing at missing paths, and that it provides a verdict and remediation steps. It appropriately declares itself 'Safe, read-only.' No contradiction with annotations.

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

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

The description is front-loaded with the primary purpose and usage trigger, then moves through return contents and the probe toggle. It is somewhat dense and list-heavy, but every clause adds useful information. It is appropriately sized for a diagnostic tool with this much output.

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 a rich output schema and full annotation coverage, so the description does not need to define every return field. It supplies the essential operational details: when to use it, what diagnostic categories it covers, what the verdict levels are, and how to switch to offline mode. This is complete enough for an agent to select and invoke it correctly.

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

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

With 0% schema coverage, the description compensates by explaining the only parameter, probe, and its offline mode. It does not restate the default (true), but the schema already provides that. The semantic distinction between live probing and offline diagnostics is clearly conveyed.

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 ('Diagnose') and resource ('Python SSL/TLS certificate configuration'), and clearly distinguishes the tool from siblings by tying it to specific failure modes (CERTIFICATE_VERIFY_FAILED, SSL errors, HTTPS failures). It also enumerates the concrete diagnostic outputs, making the 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?

It explicitly states when to use the tool: whenever any tool reports CERTIFICATE_VERIFY_FAILED, SSL errors, or HTTPS failures, including named integrations. It also provides conditional usage guidance for the probe parameter ('Set probe=False for offline config-only diagnostics').

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

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

Annotations already disclose readOnly=false, idempotent=false, destructive=false. The description adds the folder synonym and optional parent nesting, which is useful, but it does not explain behavior around duplicate names, parent_key validation, or any side effects beyond creation.

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

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

Two tight sentences with no filler. The primary action is front-loaded, and the parent option and intended use case are included directly.

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

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

For a 2-parameter creation tool with annotations and an output schema, the description covers the key points: what it creates, where, and the optional parent. It could add a short note on parent_key validity or duplicate names, but nothing vital is missing for a standard 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?

The schema has no parameter descriptions, so the description must compensate. It clarifies that parent_key relates to nesting under a parent and that name identifies the new collection, but it does not specify that parent_key must reference an existing collection key or explain name uniqueness.

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 the exact operation with a specific verb and resource: 'Create a new collection (folder) in Zotero'. It also clarifies optional nesting under a parent and frames the purpose as 'organize papers into a new group', which distinguishes it from create_item and create_note.

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

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

Explicitly provides a usage condition: 'Use this when the user wants to organize papers into a new group.' It gives clear context but does not mention when not to use it or name alternatives like add_to_collection or batch_organize.

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

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

The annotations only communicate non-read-only, non-idempotent, non-destructive behavior. The description adds meaningful context beyond that: metadata is auto-resolved, duplicates are checked, title is only used as a fallback for bare URLs, and dedup_check_failed=true is surfaced when the duplicate check fails. It stops short of explaining what happens when a duplicate is actually found, but it provides substantial 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 five sentences, each earning its place: core action, identifier types, when to use, title behavior, alternative tool, and dedup failure signal. It is front-loaded with the most important information and contains 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 tool with four parameters and an output schema, the description covers the input identifier semantics, the fallback title behavior, the alternative manual tool, and the dedup-check failure flag. The main gaps are the lack of any explanation for tags and collection_keys, and ambiguous behavior if a duplicate is found. Still, it is largely complete for an agent deciding when and 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 carries the burden of explaining parameters. It gives solid semantics for input (DOI, PMID, URL) and title (fallback for unscrapable bare URLs), but tags and collection_keys are not explained at all. With four parameters and two covered, this is partial compensation rather than full.

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: 'Add a paper to Zotero from any identifier: DOI, PMID, or URL.' It clearly enumerates accepted identifier types, which distinguishes it from manual item creation and other sibling tools without needing to inspect the schema.

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

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

It explicitly states when to use the tool ('Use this when the user wants to save a paper to their library') and when not to, naming the alternative: 'If you only have structured fields... use create_item_manual instead.' This is direct, unambiguous 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?

The description discloses the duplicate-checking behavior, which is not expressed in the annotations. It also clarifies that metadata is manually supplied rather than resolved. This goes beyond the readOnly/openWorld annotations without contradicting them.

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

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

Three short sentences: purpose first, usage condition second, duplicate check third. Every sentence adds distinct value and there is no redundant phrasing.

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

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

The description is sufficient for tool selection: purpose, alternative, and a key behavior are present. However, the tool has 15 parameters and no schema description coverage, so an agent still lacks crucial input-format guidance for non-obvious fields, making the overall definition incomplete 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 description coverage is 0% and there are 15 parameters, so the description carries the burden of explaining parameter meaning. It does not describe any specific parameter or format, leaving complex fields like creators, tags, and collection_keys undocumented in prose.

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

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

The description states a specific action and resource ('Create a Zotero item') and clearly differentiates itself from the sibling create_item by emphasizing manually provided metadata instead of resolving a DOI/URL. An agent can immediately understand what this tool does and how it differs.

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 tells the agent when to use this tool ('Use this instead of create_item when you have structured metadata already') and names the alternative. It also adds a relevant behavioral condition ('Checks for duplicates') that helps with selection.

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

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

Annotations already communicate that this is a non-read-only, non-destructive mutation. The description adds useful behavioral detail beyond those annotations: the note is attached to a Zotero item and the content can be HTML or plain text. There is no contradiction with the 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 two tight sentences with no filler. The primary action is front-loaded, and the usage guidance and content-format detail are provided efficiently. Every sentence adds meaningful 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 three-parameter create tool with an output schema and safety-relevant annotations already present, the description covers the essential relationship to the parent item and the acceptable content format. It does not describe tags or return behavior, but those are either covered by the schema, output schema, or are minor for this call context.

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

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

Schema description coverage is 0%, so the description must compensate. It does add semantic value by explaining that parent_key refers to the Zotero item the note is attached to and that content accepts HTML or plain text. However, it does not address the third parameter, tags, leaving that aspect still underdocumented.

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

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

The description names a specific verb and resource: 'Create a note attached to a Zotero item.' It further clarifies the intended use ('save reading notes, summaries, or annotations') and distinguishes this from other create actions like create_collection or create_item by specifying that the note is attached to an 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 phrase 'Use this to save reading notes, summaries, or annotations on a paper' gives clear usage context. It does not explicitly name alternatives or exclusion criteria, but the attachment-to-item framing makes it easy to distinguish from read-only siblings like get_notes and from attachment-focused tools like attach_pdf.

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?

While the annotations already mark destructiveHint=true, the description adds crucial context beyond that: the operation is IRREVERSIBLE and global, affecting everything in the trash. This is exactly the kind of behavioral disclosure an agent needs before invoking a destructive 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?

Four short sentences, each earning its place: the core action, the irreversibility warning, the global scope clarification, and the required pre-call confirmation step. No filler or repetition.

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

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

For a zero-parameter destructive tool with an output schema present, the description supplies all essential context: what is deleted, how broadly, the irreversibility, and the required user-confirmation workflow. An agent has enough to correctly decide when and 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?

The tool has zero parameters, so the schema fully covers the input surface. With 100% schema coverage and no parameters, the description has no additional parameter-level semantics to provide, and the baseline of 4 applies.

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 ('Permanently delete ALL items'), the exact resource ('the Zotero trash'), and emphasizes the global scope ('not just items you recently trashed'). It unambiguously distinguishes this from operations like trash_items or inspect_trash.

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 instructs to call inspect_trash first and to always confirm with the user, providing clear preconditions and workflow guidance. It does not explicitly name alternative tools to use instead, but the prerequisites and global-destructive warning make the intended context 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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: the output is an HTML artifact, the 'full' view caps papers at 200 by PageRank, and build_index(type='graph') must have been run first. This exceeds the annotation baseline, though it does not detail failure behavior if the prerequisite is missing.

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

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

The description is compact and front-loaded with the core purpose, then moves to usage context, parameter detail, and the prerequisite. Every sentence earns its place; there is 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?

The description covers the output format, supported views, and a prerequisite, which is substantial. Yet the 'path' parameter remains a gap in the documentation, and because the output schema already exists, return-value explanation is not needed. The missing path semantics keep it from being 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?

Schema coverage is 0%, so the description must compensate. It does richly describe the 'view' parameter, including enum values and their graph semantics, but says nothing about the 'path' parameter, which is left undocumented in both the schema and the description. Partial compensation 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: 'Export the knowledge graph as an interactive HTML visualization that opens in any browser.' It also names the exact use cases and view options, making the tool's role unmistakable even without a title.

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

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

It explicitly says 'Use this when the user wants to see their citation network visually, explore research clusters, or share a graph,' which gives clear context. However, it does not explicitly name sibling alternatives (e.g., get_citation_graph or query_knowledge_graph) or state when not to use them, so it stops short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false, so the description does not need to restate safety. It adds non-obvious behavioral detail: the exact duplicate-matching strategy (DOI match plus >85% title similarity) and optional collection scoping, which annotations cannot convey.

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

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

Two sentences: one states the action and method, the next gives use cases and optional scope. No filler or duplication of schema/annotations; every clause 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 only two optional parameters with defaults in the schema, a full safety profile from annotations, and an output schema. The description supplies the remaining needed context: purpose, matching criteria, typical triggers, and collection scoping. Nothing an agent needs to call it correctly 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?

Schema description coverage is 0%, so the description must compensate. It paraphrases collection_key ('Optionally scoped to a single collection') but never explains limit, including what its value represents or how the string/integer variants are interpreted. With half the parameters undocumented in both schema and description, this is a clear 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 opens with a specific verb ('Scan'), a concrete resource ('the Zotero library'), and the goal ('duplicate items'), plus the method (DOI match and title similarity >85%). This is clearly distinct from siblings like search_items or get_collection_items, which serve different lookup tasks.

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 states when to use it: when the user wants to clean up a library or after bulk imports. It does not name alternatives or when-not-to-use cases, but the use-case context is clear enough to route an agent.

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

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive behavior. The description adds value beyond that by disclosing the external Semantic Scholar dependency, the seed-based recommendation behavior, and the in_library flag on each result. It does not mention failure modes or external service limitations, but the annotation coverage lowers the burden.

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. The purpose is front-loaded, the usage trigger comes next, and the seed guidance and result flag are delivered succinctly. Every sentence contributes to correct invocation.

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 read-only recommendation tool with rich annotations and an output schema, the description covers purpose, usage trigger, seeding behavior, and a key output characteristic. It could more explicitly distinguish itself from search_items or get_citation_graph, but the core information needed to invoke it safely and correctly is present.

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

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

Schema description coverage is 0%, so the description must compensate. It does add meaningful semantics for item_keys by framing them as seeds and noting that more seeds improve recommendations. However, it does not describe limit at all, leaving a common parameter to be inferred from its name and default value.

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

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

The description uses a specific verb ('Find papers related to items in your library') plus the mechanism ('via Semantic Scholar recommendations') and analogies to Connected Papers/ResearchRabbit. This clearly differentiates it from library search and citation-graph siblings, and the 'when the user wants to discover new papers' phrasing reinforces the intended purpose.

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

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

The description explicitly states when to use the tool: 'Use this when the user wants to discover new papers on a topic.' It also gives seeding guidance ('the more seeds, the better the recommendations'). However, it does not explicitly state when not to use it or name competing sibling tools such as get_citation_graph or search_items.

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

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

Annotations already signal read-only, idempotent, open-world behavior. The description adds useful context beyond annotations: it queries OpenAlex and flags each result with in_library. It does not cover rate limits or pagination, but the safety profile is already carried by 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?

Three compact sentences with no waste: the first states the core operation and source, the second gives usage triggers, and the third notes the result flag and direction choices. Well 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?

With an output schema and read-only annotations present, the description sufficiently orients the agent with purpose, usage, output flag, and direction values. The only minor gap is not addressing how this relates to similar sibling tools like find_related_papers.

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 direction enum values and indicates item_key identifies a Zotero item, but it does not clarify limit semantics or item_key formatting. Partial compensation 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?

States a specific verb and resource: 'Get papers that cite or are cited by a Zotero item' via OpenAlex. It clearly conveys the citation-network scope and direction options, though it does not explicitly distinguish itself from the sibling find_related_papers.

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

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

Provides explicit usage context: 'Use this when the user wants to explore a paper's citation network, find related work, or trace the influence of a paper.' It does not mention when not to use it or name alternative tools, but the usage context 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?

Annotations already signal read-only, idempotent, and non-destructive behavior, so the description carries a lighter burden. However, it adds no detail about pagination behavior, default limits, or how 'all items' relates to the limit/offset parameters. There is no contradiction with the 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?

Two compact sentences with no filler. The core verb and resource are front-loaded, and the usage context appears in the second sentence. Efficient and easy to parse.

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 output schema and annotations cover the return shape and safety profile, but the description omits important invocation details such as pagination semantics, response_format options, and how this tool differs from search_items for filtered collection queries. It is adequate for the common folder-contents request but incomplete for nuanced parameter 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, but it only clarifies collection_key ('by its key'). limit, offset, and response_format are left entirely to schema names and defaults; the response_format enum values are not explained, and the phrase 'all items' can mislead given the default limit of 100.

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 the exact action ('List all items') and the specific resource ('a specific Zotero collection by its key'), plus user-facing context ('folder/collection'). This clearly distinguishes it from sibling tools like get_collections, which lists collections rather than items, and get_item, which targets a single 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?

Explicitly provides a usage trigger: 'Use this when the user wants to see what's in a particular folder/collection.' It does not mention when not to use it or point to alternatives like search_items for filtered searches, so it stops short of a full 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?

Annotations already cover readOnly, idempotent, non-destructive, and open-world behavior. The description adds that it lists all collections with scoping information, but it does not disclose pagination, sorting, or output size limits. No contradiction with annotations.

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

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

Two tight sentences with no filler. The main function is front-loaded, and the usage guidance follows immediately. 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?

Given the simple optional parameter, the rich annotations, and the presence of an output schema, the description is nearly complete. A small gap is not mentioning response_format or explicitly contrasting with get_collection_items, but the core use case and return contents are well covered.

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

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

Schema description coverage is 0%, and the description does not mention the response_format parameter at all. While the enum values 'json' and 'markdown' are self-explanatory, the description does not compensate for the absent parameter documentation as required for low-coverage schemas.

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

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

The description uses a specific verb ('List') and specific resource ('collections (folders) in the Zotero library'), and enumerates the exact returned fields: keys, names, parent relationships, and item counts. This clearly distinguishes it from sibling tools like get_collection_items.

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

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

The description explicitly states when to use it: when the user asks about their library organization or wants to browse/find a collection. It provides clear context but does not explicitly mention when not to use it or name alternative 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context about returning detailed metadata and supporting BibTeX export, but it does not disclose potential open-world response behavior or errors beyond what annotations already imply.

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

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

The description is three short sentences with no filler. The core operation is front-loaded, the use case is stated, and the BibTeX instruction is a concise, actionable detail. 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 is simple, annotations cover safety, and an output schema exists, so the description need not explain return values. The only notable gap is the undocumented 'response_format' parameter, but the schema's clear enum values partially compensate. Overall, the description is sufficient for correct invocation in most 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 clarifies 'item_key' as the identifying key and explains that format='bibtex' switches to BibTeX export, but it completely omits the 'response_format' parameter, which is one of three parameters and controls JSON vs Markdown output.

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 ('Get detailed metadata'), the resource ('a single Zotero item by its key'), and the use case ('full bibliographic details'). It also distinguishes itself from broader search or collection tools by focusing on a single item key, making the 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 explicitly says 'Use this when you need full bibliographic details... for a specific item,' which gives clear usage context. It does not name sibling alternatives or state when not to use it, but the use case is specific enough for an agent to select this tool appropriately.

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

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

Annotations already supply the read-only, idempotent, non-destructive safety profile. The description adds useful behavioral context on top by specifying the return shape and enumerating the availability statuses. It doesn't discuss rate limits or auth, but for this simple read tool that is not a significant omission.

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, front-loaded with the verb and object, and no filler. The use case, alternative, and return format each earn their 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 is simple, has a full output schema, and the annotations cover safety. The description goes beyond what is required by explaining the availability enum and pointing to get_pdf_content. It lacks an explicit definition of parent_key, but the name plus 'on a Zotero item' makes the tool callable.

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

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

The schema only provides parent_key with type string and zero description coverage, so the description must compensate. It clarifies that the key refers to a Zotero item, but it does not specify the key's format or how to obtain it. For a single self-named parameter this is adequate but not rich.

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

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

The description names a specific action ('List file attachments'), a specific resource ('a Zotero item'), and a distinctive output dimension ('availability status'). It also explicitly contrasts with get_pdf_content, so an agent can distinguish this tool from its closest sibling without inspecting the schema.

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

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

Gives explicit when-to-use guidance: 'Use this to check whether a paper HAS a PDF before fetching it.' It also names the alternative for a different task: 'to actually read the content, use get_pdf_content.' This is a clear decision rule.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds semantic context about what qualifies as a note, but does not disclose operational behavior such as pagination, ordering, or scope limits.

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

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

Two sentences with no filler. The core action is front-loaded in the first sentence, and the usage guidance occupies a natural second sentence.

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 low-complexity read-only tool with an output schema and safety annotations, the description covers purpose and usage well. The only notable gap is the undocumented parent_key parameter, so it is nearly complete but not fully self-contained.

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

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

Schema description coverage is 0%, and the description never explains parent_key, its format, or how to obtain it. The phrase 'attached to a Zotero item' weakly implies parent_key identifies that item, but this does not meaningfully compensate for the missing documentation.

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

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

States a specific verb and resource: 'Get all notes attached to a Zotero item.' It clarifies what kinds of notes are included (annotations, reading notes, comments), which distinguishes it from sibling tools like get_item_attachments or get_pdf_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?

Explicitly says 'Use this when the user wants to read their annotations, reading notes, or comments on a paper,' giving clear context for when to call it. However, it does not name alternatives or state when not to use it, so it stops short of the highest bar.

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

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

The annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond that: the routing to sources, the extract_text behavior, and the content_source response field with its possible values. It does not fully enumerate all response fields, but the output schema covers that.

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 dense sentences deliver purpose, routing, usage boundary, parameter behavior, and response contract. There is no filler, and the most decision-relevant 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?

For a tool with routing complexity, an output schema, and multiple annotations, the description covers the essential decisions: when to use, how to request inline text, and what primary response discriminator to expect. It could mention how the caller should consume the returned file path or PMCID, but the output schema likely handles that.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It clearly explains extract_text's effect on output, and item_key is inferable as the paper identifier, but its format and provenance are not explicitly explained. Some improvement would be describing what an item_key is or how to obtain one.

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

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

The description opens with a specific verb-resource pair ('Get the full text of a paper in the library') and immediately details the routing behavior across sources. It also distinguishes itself from get_item_attachments, making its purpose and scope 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?

Explicitly states when to use this tool ('when the user wants to read a paper's content') and when not to ('to only CHECK whether a PDF exists', use get_item_attachments first). This direct alternative guidance leaves no ambiguity about selection.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond those annotations: the selection criteria (has abstracts, missing extracted entities), the entity types involved, and the recommended next step. No contradictions with annotations.

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

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

Two concise sentences deliver the core purpose, usage trigger, and follow-up workflow without filler. The most important information is front-loaded in the first sentence.

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 is simple, has one optional parameter, and an output schema exists. The description explains what papers are returned and how to proceed. The only minor gap is the undocumented limit parameter, but the default of 50 and the intuitive name mitigate the issue.

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

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

The single parameter 'limit' has 0% schema description coverage, and the tool description does not explain its semantics, accepted formats, or behavior. The name is somewhat intuitive, but the schema's anyOf string/integer design is left undocumented, so the description does not compensate for the schema gap.

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

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

The description clearly states the specific action and resource: get papers that have abstracts but no extracted biomedical entities yet. It identifies the exact purpose—finding papers that need entity extraction—and distinguishes this from related sibling tools like store_entities and search_entities by narrowing the resource state.

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 says 'Use this to find papers needing entity extraction' and provides the intended follow-up workflow with store_entities. There are no explicit when-not-to-use instructions or alternative tool mentions, but the usage context is strong enough for an agent to select this tool appropriately.

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

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

Annotations indicate a mutation (readOnlyHint=false) but not destructiveness; the description adds useful behavioral detail by stating that markers get replaced with field codes and that existing formatting, styles, images, and layout are preserved. It stops short of explaining whether the file is modified in place or whether output_path changes that 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?

Three sentences, front-loaded with the main function, followed by routing guidance and preservation guarantees. There is no filler or repetition of schema 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?

The description is complete enough for an agent to understand what the tool does, when to use it, and what side effects to expect. The only notable gap is the absent explanation of output_path semantics, which matters slightly 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 coverage is 0%, so the description must compensate. It adds clear meaning for document_path by describing the .docx with markers, but it does not explain output_path at all, including what a null default means. This is a partial compensation for the schema's lack of parameter 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?

States a specific verb ('Insert'), resource ('live Zotero citation field codes into an existing Word document'), and mechanism (replaces [@ITEM_KEY] markers with Zotero field codes). It also explicitly distinguishes itself from write_cited_document, so an agent can select it without opening schemas.

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: 'Use this to add citations to a document the user already has.' It also names the alternative for the contrasting case: 'to create a NEW .docx from markdown instead, use write_cited_document.'

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context by connecting the read to the destructive consequence of empty_trash, helping the agent surface the right information before an irreversible 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?

Two tight sentences with no filler. The primary action is front-loaded, and the critical usage warning is stated in the second sentence without 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?

For a zero-parameter read-only tool with an output schema and clear annotations, the description covers everything an agent needs: what the tool lists, the field types returned, and when to call it relative to empty_trash.

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, so the baseline is 4. The description does not need to explain parameters, and it appropriately focuses on behavior and output instead.

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

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

The description names a specific verb ('List'), a precise resource ('the Zotero trash'), and the returned content ('item type and title'). It is clearly differentiated from destructive siblings like empty_trash and from other read tools in the sibling list.

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

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

It explicitly instructs when to use this tool: 'BEFORE empty_trash'. It also explains why and highlights the alternative's global, irreversible nature, leaving no ambiguity about the intended workflow.

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

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

The description discloses far more than the annotations provide: it marks 'remove' as DESTRUCTIVE, states deletion is 'not reversible,' and notes that both remove and rename apply 'library-wide.' It also instructs the agent to confirm with the user before these actions, which is essential behavioral guidance.

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 purpose, then packs action-specific details into a compact list. Every sentence contributes critical information, with no filler 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?

For a tool with four optional parameters, an output schema, and destructive behavior, this description covers the operational essentials: actions, parameter requirements, global scope, irreversibility, and confirmation step. Nothing an agent needs to safely invoke this tool 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?

Despite 0% schema description coverage, the description maps every parameter to its role: 'list' uses an optional prefix filter, 'remove' requires tag, and 'rename' requires both tag and new_tag. This adds significant meaning beyond the bare schema and resolves the action-dependent requirement ambiguity.

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 'Manage tags in your Zotero library' and immediately enumerates concrete actions: list, filter, remove, and rename. It clearly scopes the tool to tag operations, which distinguishes it from the mostly item/collection-focused sibling tools even without naming a specific alternative.

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

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

It explicitly states 'Use this when the user asks about tags, wants to list/filter tags, remove a tag from all items, or rename a tag,' giving clear invocation criteria. It does not name alternate tools or provide explicit when-not-to-use conditions, so it misses the full top 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description adds crucial behavioral details: dry-run default, apply=true gate, hash verification, moving originals to trash, and explicitly never emptying trash. No contradiction with annotations exists.

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

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

The description is compact and front-loaded with the core workflow and purpose, then provides essential safety warnings. Every sentence adds value: the process, the quota benefit, the dry-run requirement, and the trash-handling exclusion.

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 destructive, multi-step migration tool, the description covers the main workflow, safety gates, and sibling routing well. However, it omits details on several parameters (limit, modes, dest_dir, include_local_only) that could matter for correct execution, leaving some contextual gaps despite the output schema.

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

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

Schema description coverage is 0%, so the description must compensate, but it only clarifies apply=true and indirectly mentions trash_originals. The meanings of limit, modes, dest_dir, and include_local_only remain unexplained, leaving the agent to guess at important behavioral controls.

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

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

The description states a specific verb and resource: 'Convert Zotero imported (cloud-stored) attachments into linked files' with a concrete process (copy/download, hash-verify, create linked_file, trash original). It also names the related sibling plan_attachment_migration and contrasts with inspect_trash/empty_trash, making differentiation clear.

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

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

The description gives explicit usage conditions: it defaults to a dry run, requires apply=true only after showing plan_attachment_migration output, and explicitly redirects trash-emptying to inspect_trash then empty_trash. This provides both when-to-use and when-not-to-use 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?

The description goes beyond the readOnlyHint/destructiveHint annotations by explicitly stating 'Nothing is written, downloaded, or trashed.' It also discloses what the planning report includes: attachments that would be converted, ones requiring download first, and skip reasons. This is transparent about side effects and operational 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 compact and well structured: purpose is front-loaded, read-only behavior is explicitly highlighted, and the migration sequencing note is placed at the end. Every sentence adds useful information with 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?

The high-level context is strong: it explains the tool is a safe planning step, what it inventories, what it reports, and that it should precede migrate_attachments. The output schema exists, so return-value details are not needed. However, all five optional parameters are completely undocumented, leaving customization to inference, so completeness is only moderate.

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

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

Schema description coverage is 0% and the description provides no explanation of limit, modes, dest_dir, response_format, or include_local_only. An agent cannot infer what modes values are valid, what limit controls, or how dest_dir affects planning. This is a complete gap in parameter semantics.

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 ('Plan a migration') and identifies the exact resource ('Zotero imported (cloud-stored) attachments to linked files') with a clear goal: free cloud storage while keeping PDFs local. It also distinguishes itself from the follow-up sibling migrate_attachments by explicitly framing itself as the read-only precursor.

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 clearly instructs 'Run this before migrate_attachments,' giving an explicit temporal usage context. It doesn't spell out when not to use it or compare it to other alternatives, but the sequencing guidance is strong and actionable.

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

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the bar is lower. The description adds meaningful behavior beyond those annotations: the dependency on a pre-built graph index, ranking semantics ('summed PageRank', 'ranked by shared papers'), and the meaning of hops/depth for the network query. It does not describe error cases if the index is absent, but the prerequisite is disclosed.

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

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

The description is dense but not bloated. Every sentence earns its place: purpose, usage trigger, query-type definitions, and a prerequisite. The most important behavioral constraint is placed at the end but clearly signposted, and there is no filler or restatement of the tool name.

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 — five query modes, an optional depth, an author-name parameter, and a prerequisite — the description covers all essential operational knowledge. An output schema exists, so detailed return-value documentation is unnecessary. The only small gap is the undocumented limit parameter, but defaults and schema metadata mitigate that.

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

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

Schema description coverage is 0%, so the description must carry the parameter documentation. It explains all query_type enum values, clarifies author_name for coauthors_of and network, and defines depth as hops. The limit parameter is never mentioned, and it is not systematically stated which query types ignore author_name, so the coverage is strong but not complete.

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

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

The description names a specific resource ('author co-authorship network') and a clear verb ('Query'), then enumerates five concrete query types that define exactly what the tool does. The scope is distinct from sibling graph tools such as get_citation_graph or query_knowledge_graph, so an agent can identify it confidently.

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 tells the agent when to use the tool: when the user asks about prolific authors, collaborations, or an author's network. It also adds a critical prerequisite ('build_index(type='graph') must be run first'). However, it does not name alternative tools or give when-not-to-use exclusions, stopping 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?

Annotations already establish readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: the dependency on build_index, the notion of PageRank-ranked papers, shortest citation paths, hop-based neighborhoods, and month-by-month citation velocity. This helps the agent anticipate what each query actually computes and what state it requires.

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 long but earns its length because it must document ten distinct query types with varying parameter requirements. The most important guidance (when to use and the prerequisite) is front-loaded, and the query-type inventory is dense with useful information rather than padded.

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 — 11 parameters, 10 query types, and a prerequisite — the description covers the key usage dimensions: when to use it, what each query type means, which parameters each requires, and what must happen first. The output schema handles return-value documentation. Minor gaps remain for generic parameters like topic and years, but overall the description is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate, and it largely does by mapping query types to required and optional parameters: path needs doi_a and doi_b, neighborhood needs doi plus optional depth, citation_velocity needs doi, trending takes limit and years, and timeline takes topic/start_year/end_year. It leaves a few generic parameters like response_format and exact date formats implicit, but the core parameter-to-query-type relationships are explained.

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

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

The description names a specific action and resource ('Query the knowledge graph') and immediately enumerates ten concrete query types that distinguish it from sibling tools like get_citation_graph or find_related_papers. It also states the exact user intents it serves ('influential papers, research clusters, publication trends, or relationships between papers'), making it unambiguous what this tool is for.

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 start conditions: 'Use this when the user asks about influential papers, research clusters, publication trends, or relationships between papers,' and it states a hard prerequisite ('Requires build_index(type="graph") to be run first'). It does not explicitly mention when not to use it or name alternative sibling tools, so it falls short of a 5 but is clearly above vague.

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

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

Annotations already cover read-only/idempotent/non-destructive behavior. The description adds per-query constraints such as 'requires doi_a and doi_b' and 'requires doi', which are behavioral details beyond the bare schema.

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

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

The description is compact, front-loaded with the primary purpose, and uses a list to present query types efficiently. The inline list is dense but each clause adds needed routing 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 read-only tool with an output schema, the description provides enough context to choose a query type and identify required DOI inputs. Minor gaps remain around limit and entity field usage, but the main invocation path is fully specified.

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 parameter descriptions are absent (0% coverage), and the description compensates by mapping query_type values to their intended fields and required DOI parameters. It does not explain the limit parameter or explicitly bind entity_name/entity_type to their query modes, leaving some semantics to inference.

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

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

The description states a specific object ('biomedical entity graph') and enumerates five concrete query modes with their outcomes. It clearly distinguishes entity-graph search from generic search tools by specifying user intents (papers, co-occurrences, shared entities).

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

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

It gives explicit 'Use this when...' triggers for entity-relationship questions and explains which query type fits which request. It does not name sibling alternatives or state when not to use it, so it omits exclusionary guidance.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds valuable contextual behavior beyond annotations: it requires build_index(type='fulltext') to be run first and returns 'highlighted text snippets.' This is useful operational information not present in the schema or 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 three sentences with no filler. The primary action is first, usage guidance follows, and the prerequisite is tucked in at the end. Every sentence adds operational value.

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

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

For a simple read-only search with an output schema and safety annotations, this description is nearly complete: it explains scope, result format, and required precondition. It is missing only minor clarifications such as limit semantics or behavior when the fulltext index is absent.

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 gives meaning to the query parameter ('specific term, method, drug, or concept'), but the limit parameter is never explained—especially its unusual dual string/integer type. This is a meaningful gap for a tool with only two parameters.

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

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

The description states a specific verb and resource: 'Search the full text of indexed PDFs in your library.' It clearly distinguishes itself from title/abstract-level searching by saying 'not just titles/abstracts,' which separates it from sibling tools like search_items.

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 says when to use the tool: 'when the user wants to find papers that mention a specific term, method, drug, or concept in their body text.' It also highlights the exclusion of titles/abstracts and a prerequisite (build_index). However, it does not explicitly name an alternative tool or state when not to use it.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful behavioral context beyond annotations by specifying that matching covers title, author, and tag, and that item_type and exact tags act as filters. There is no contradiction with the 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 three short sentences with no filler. It front-loads the core action, follows with concrete usage triggers, and ends with filter semantics. Every sentence contributes.

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 read-only search tool with an output schema and clear annotations, the description supplies enough behavioral and parameter context to invoke it correctly. The main gap is not distinguishing this metadata search from search_fulltext, which would improve routing in ambiguous requests.

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% parameter description coverage, so the description carries the burden. It clarifies the meaning of the required query parameter, gives an item_type format example ('journalArticle', 'book'), and explicitly notes tag matching is exact. Pagination and response_format are left to self-explanatory names and the enum, so coverage is strong but not complete.

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

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

The description states a specific verb and resource ('Search Zotero library items by keyword') and clarifies the matching modes (title, author, tag). It does not explicitly name sibling tools like search_fulltext, so differentiation from them relies on the 'title/author/tag' qualifier, which prevents a 5.

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

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

The description explicitly states when to use it: 'when the user asks to find papers, look up references, or search their library.' It gives clear context but does not provide when-not-to-use guidance or mention alternatives such as search_fulltext, so it stops short of full exclusivity guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds that output includes fix instructions for misconfigured modes. It also frames the tool as a connectivity check, which is useful behavioral context beyond the flags.

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

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

Two sentences, front-loaded with the core action and followed by actionable usage guidance. No filler or repetition of schema/annotation fields.

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

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

With a parameterless schema, an output schema present, and annotations covering safety, the description covers why, when, and what to expect. An agent can invoke it correctly with no further information.

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?

There are zero parameters, so the description has no semantic burden beyond the baseline. No parameter documentation is needed.

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 ('Check') against a concrete resource ('Zotero MCP operating modes') and states it also returns fix instructions for misconfigured modes. This sets it apart from the collection/item/search siblings by focusing on server-level diagnostics.

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?

Explicitly tells the agent to call this tool first when tools return 'unavailable' errors or when starting a new session to verify connectivity. It lacks an explicit 'when not to use' or named alternatives, but the trigger conditions are strong enough for routing.

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

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

The description confirms a mutating write ('Store') and the annotations show readOnlyHint=false, so there is no contradiction. It also adds useful context about accepted entity types and the extraction workflow. However, it doesn't disclose storage semantics such as whether re-storing the same DOI merges, replaces, or duplicates entities; this gap is notable given the idempotentHint=false annotation.

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

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

Four short sentences, each with a distinct job: purpose, trigger, type vocabulary, and input shape. The most important information is front-loaded, and there is 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?

With one parameter, an existing output schema, and low overall complexity, the description is largely complete for selecting and invoking the tool. It provides the trigger, data shape, and allowed entity types; the main residual gap is the lack of merge/replace/duplicate semantics, but that is not required to make a correct first call.

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 0% description coverage and only says 'results' can be a string or an array of empty items. The description fills this gap by specifying the expected payload shape—'list of {doi, entities: [{name, type}]}'—and enumerating valid entity types. It is slightly under-specified because it doesn't mention the allowed string form or exact doi format, but it gives enough to construct a valid call.

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

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

The description opens with a specific action and object: 'Store extracted biomedical entities for papers.' This clearly distinguishes it from siblings like search_entities (retrieval) and get_unextracted_abstracts (extraction), letting an agent tell what the tool is for without opening the schema.

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

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

It explicitly states when to call: 'Call this after extracting entities from abstracts (via get_unextracted_abstracts or any paper reading).' This gives a clear workflow condition and names a prior step. It doesn't list exclusions, but there is no obvious alternative tool for persisting entities, so the guidance is sufficient.

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

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

The annotations already mark this as destructive, but the description adds essential nuance: the action is reversible and items can be restored from Zotero trash. It also instructs the agent to confirm with the user, which is important behavioral guidance beyond what annotations express. No contradiction with annotations exists.

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

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

The description is compact and front-loads the primary purpose and reversibility, followed by usage context, parameter guidance, and confirmation guidance. Every sentence adds meaningful information without redundancy or filler.

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

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

For a one-parameter tool with an output schema and useful annotations, the description covers purpose, when to use it, the key behavioral nuance of reversibility, parameter expectations, and user-confirmation expectations. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, but the description compensates by explicitly stating that the tool 'accepts one or more item keys,' directly clarifying the sole parameter's semantics. It does not explain how to source item keys or provide format details, but given the parameter's simplicity this is sufficient.

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

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

The description states a specific action ('Move Zotero items to trash') with a clear resource and a key qualifier ('reversible'). It also frames the tool's use case ('when the user wants to delete papers') and implicitly distinguishes it from permanent deletion via empty_trash.

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 says when to use the tool: when the user wants to delete papers. It also adds a practical guardrail: confirm with the user before trashing. However, it does not name alternatives or say when not to use it, such as when permanent deletion is needed.

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

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

Annotations already flag this as destructive and non-read-only. The description adds valuable context beyond those hints by disclosing optimistic locking, 'to prevent overwriting concurrent changes,' which tells the agent how concurrent edits are handled. This is meaningful behavioral information not present in the 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?

Three short sentences with no filler. The main action and target resource are front-loaded, the use case follows, and the locking behavior closes the description. 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?

Given the simple two-parameter schema, the existing output schema, and annotations that already convey destructive/read-only behavior, the description covers the important operational detail (optimistic locking) and typical usage. It is slightly incomplete on item_key semantics, but overall sufficient 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 description coverage is 0%, so the description must compensate. It gives semantic meaning to the 'fields' parameter by listing title, author, date, DOI, and other bibliographic fields, but it does not explain the 'item_key' parameter or why 'fields' may be a string. Some value added, but the gap remains.

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: 'Update metadata fields on an existing Zotero item.' It lists concrete field examples (titles, authors, dates, DOIs) and the word 'existing' distinguishes this from creation tools like create_item or create_item_manual.

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

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

The description gives a clear use case: 'Use this to correct titles, authors, dates, DOIs, or other bibliographic fields.' This tells an agent when to invoke it, though it does not explicitly exclude alternatives such as batch_organize or manage_tags.

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

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

The description adds useful behavioral context beyond the annotations, including the [@ITEM_KEY] citation syntax and the 'live Zotero citations' behavior. However, it does not disclose whether an existing file at output_path is overwritten, what happens if Zotero is unavailable, or any other side effects of writing the file.

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

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

The description is compact and front-loaded: the core purpose appears first, followed by the citation syntax and usage guidance. Every sentence earns its place with 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 two-parameter tool with an output schema, the description covers the essential operational context: input format, citation mechanism, output artifact, and when to choose a sibling tool. Minor gaps such as output_path path expectations and overwrite behavior prevent a 5.

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 both parameters. It does clarify that content is markdown text containing [@ITEM_KEY] citation markers, but it leaves output_path unexplained beyond its name, without format or constraint details.

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

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

The description names a specific verb and resource: creating a new Word document from markdown text with live Zotero citations. It also distinguishes itself from insert_citations, making the tool's purpose unmistakable.

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 says when to use this tool: when writing a new document from scratch such as a literature review or manuscript draft. It also names the alternative insert_citations for adding citations to an existing document.

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