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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavior beyond that: default page count, default character count, max_chars bounds, the 50-page limit, continuation guidance, and the auto-selection caveat for parent Zotero items. This is rich, useful context.

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

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

Four dense sentences, each adding distinct value: purpose, defaults and limits, continuation guidance, and an important caveat. The most identifying information is front-loaded and there is no filler or repetition of the schema.

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

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

An output schema exists, so return values do not need explanation. The description covers core behavior, constraints, and an important sibling alternative. The only real gap is the underspecified offset and expected_sha256 semantics, but defaults make the tool callable without those details.

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

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

Schema description coverage is 0%, so the description must compensate. It does clarify the ID scheme, max_chars range and default, page-selection limits, and the importance of retaining expected_sha256. However, offset and the exact meaning of expected_sha256 are not fully explained, so it 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 uses a specific verb and resource: 'Read a source excerpt by file:, zotero:, project: or feedback: ID.' This clearly distinguishes it from siblings like list_files, search, and read_page_image, and names the ID formats it accepts.

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 routing guidance: 'Use get_writing_context for project IDs.' It also provides operational guidance about continuing only as needed and retaining page range and expected_sha256. It does not explicitly state when to prefer fetch over siblings, but the purpose distinction is strong enough.

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

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

Annotations already mark it read-only, idempotent, and non-destructive; the description adds value beyond that by specifying what the tool actually inspects and by disclaiming that it will not load writing/research context or experiment records. 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 front-loaded sentences with no filler. The first states what it does; the second prevents a common misuse. 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 zero-parameter status tool with an output schema and strong annotations, the description covers purpose, scope, and an important exclusion. No additional information is necessary 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?

There are zero parameters and the schema has 100% coverage (empty properties), so there is nothing for the description to clarify. 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?

Description uses a specific verb ('Check') and names the exact scope: library health, PDF/full-text coverage, and enabled capabilities. It also draws a boundary by saying it does not load writing/research context or experiment records, making the purpose distinct from siblings like fetch and search.

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

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

The description gives clear context: use it for health/coverage/capability checks. The explicit 'Does not load...' sentence provides a when-not condition, but no sibling alternative is named, so it stops short of a full routing guide.

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 non-obvious context: folder paths are relative, hidden files are excluded, paths outside the configured folder are excluded, and results contain file: IDs for downstream fetch. This is genuinely useful behavioral disclosure 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?

Two sentences with no filler. The primary purpose is front-loaded, and the secondary details about relative paths, exclusions, and file IDs are compact and meaningful.

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 communicates the core browsing behavior and folder constraints, and an output schema exists to document return values. However, it leaves limit, offset, and recursive semantics undocumented, and it lacks explicit guidance for choosing between list_files and the search/fetch siblings. These are meaningful completeness gaps for an agent calling the tool.

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

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

Schema description coverage is 0%, so the description must compensate. It only clarifies the folder parameter ('folder is relative'), while limit, offset, and recursive receive no explanation. For a tool with four parameters but zero schema descriptions, this is a significant gap.

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

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

States a specific action and resource: 'Browse the local literature folder.' It clarifies folder scope, notes that results contain file: IDs for fetch, and excludes hidden files and paths outside the configured folder. This makes the tool's purpose distinct from siblings like search and fetch.

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

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

The description implies when to use it: when browsing the local literature folder, and it tells agents that file IDs in results are intended for fetch. However, it does not explicitly contrast with search or other siblings, nor state when not to use list_files.

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

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

Annotations already mark the tool read-only, idempotent, and non-destructive, so the description only needs to add operational context. It adds the Poppler prerequisite and notes that page numbering is 1-based, which is useful, but it does not describe the return format or failure behavior. This matches the lower bar for annotation-backed tools.

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 purpose is front-loaded, and the indexing detail and prerequisite are separated cleanly.

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

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

For a simple read-only tool the description is mostly sufficient, and the Poppler prerequisite is helpful. However, with no output schema and an unexplained 'id' parameter, the agent is left to infer where the id comes from and what form the returned image takes.

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

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

Schema description coverage is 0%, so the description must compensate for undocumented parameters. It clarifies that 'page' is 1-based, but the required 'id' parameter is never explained, leaving ambiguity about what identifier should be passed and where it comes from.

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 ('Inspect an original PDF page as an image') and a clear resource, with concrete use cases like plots, tables, equations, and scanned pages. It is clear about what the tool does, but it does not explicitly differentiate from siblings such as fetch or search, so it stops short of 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 phrase 'especially for plots, tables, equations or scanned pages' gives a clear context for when this tool is appropriate, implying it is for visual content where text-based extraction may fail. It does not state exclusions or explicitly name alternatives, but the guidance is otherwise 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 mark the tool as readOnly, idempotent, and non-destructive. The description adds meaningful behavioral limits beyond those annotations: uncached PDFs are not full-text searched, and query terms are matched lexically on the same page. This is valuable operational context for setting agent expectations.

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 core scope and return value are front-loaded, and the important limitation about uncached PDFs is placed at the end without bloating the description.

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 search surface, return contents, and a key limitation, and an output schema exists to document return structure. However, it does not explain parameter behavior or provide guidance for choosing among siblings, leaving the definition slightly incomplete for a tool with low schema coverage.

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

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

Schema description coverage is 0%, so the description must compensate for the two parameters, but it does not explain query or limit semantics. The phrase 'query terms' hints at the query parameter, and limit likely controls result count, but neither is explicitly defined.

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 ('Search') and distinct resources: live Zotero metadata, local file names, and cached PDF/text content. It also differentiates from siblings by noting it returns IDs for fetch, snippets, and indexing coverage, which separates it from list_files, fetch, and read_page_image.

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

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

The description makes the intended use clear: search across metadata, file names, and cached content, returning IDs that could be passed to fetch. It does not explicitly name alternatives or state when not to use it, so it stops short of a 5, but the context is clear enough for an agent to select it sensibly.

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