Professor' Harvester

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

Despite readOnlyHint=true, the description goes well beyond annotations: it discloses that listing extracts nothing, that member retrieval converts to Markdown, that 0 members means an empty archive, and that an ERROR item represents fetch/open/refusal failures including traversal, symlink, and size cases. This gives the agent accurate expectations for edge cases.

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 earns its place: it states the resource, gives example phrasings, excludes the sibling tool, defines the two-phase call pattern, and enumerates error/empty outcomes. No filler or redundant restatement is present.

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 rich annotations, this is complete. There is no output schema, but the description explains the return semantics well enough: listing returns names and sizes, member returns Markdown, 0 members means empty, and ERROR signals the failure modes. An agent has everything needed 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 coverage is 100%, so the baseline is 3. The description adds meaningful workflow semantics beyond the schema by establishing the ordering of listing first and then member selection, and it reinforces the safety distinction between the two modes. This is a modest but real enhancement over the schema text.

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 plus resource ('Browses a compressed archive'), then clarifies it is not a web page fetcher by naming the destination for URLs. It clearly distinguishes itself from the fetch sibling while defining both listing and member-extraction modes.

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 a URL to a page goes to fetch, naming the alternative tool and the condition that routes there. It also provides a concrete two-step usage pattern: call with source first for the listing, then with member to convert that entry to Markdown.

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 readOnlyHint, the description discloses important behavioral details: content may be truncated and the path to the full artifact is provided, failing items return their own errors while others still succeed, and empty extractions are reported as errors rather than blank bodies. It also surfaces cache-related behavior, which the annotation does not 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?

The description is compact and informative: four sentences cover purpose, call syntax, return shape, and failure behavior without filler. Every sentence earns its place, and core operational constraints are 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 no output schema, the description fully explains what each item returns, including truncation, size, cache status, and the path to the complete artifact. Combined with the schema's parameter documentation and the readOnlyHint annotation, an agent has all the context needed to invoke fetch correctly and interpret its results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by showing valid source forms (URL, doi:, harvest:) and stating that results preserve input order, which goes beyond the schema's property descriptions. Refresh and size_only remain covered by the schema, so the description did not need to restate them.

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 precise verb and resource: retrieves 1–50 documents as Markdown while preserving input order. It distinguishes itself from siblings by specifying what fetch accepts (URLs, DOIs, ISBNs, PMID/PMCIDs, harvest handles) and explicitly routes titles to findWorks, images to fetchImage, and archives to archive.

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

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

The description gives concrete usage guidance: identifiers from locations or unambiguous document identifiers go to fetch, while a title should go to findWorks first, with the resulting handle then passed to fetch. The schema reinforces exclusions for titles, images, and archives, leaving no ambiguity about when this tool is the right choice.

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 readOnlyHint annotation, the description discloses that images are never OCR'd or converted, that results preserve input order and include paths plus bytes, and that a failing item is isolated while the rest still return. This is substantial behavioral context that an agent cannot infer from the schema alone.

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 carry the purpose, a usage example, parameter constraints, return format, partial-failure behavior, and sibling routing with no filler. The vision-oriented use case is front-loaded, and every sentence earns its place.

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

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

For a single-parameter tool with no output schema, the description fully covers accepted input types, limits, ordering, return values, error isolation, and the key alternative. An agent has everything needed to select and 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?

The schema already documents the sources array, its 1–50 item boundaries, and the path/order behavior. The description adds value by including a concrete invocation example and mentioning 'harvest handles' as an accepted input form not listed in the schema. This is meaningful but not essential enrichment over near-total schema coverage.

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 resource: fetching images as local files for vision. It includes natural-language triggers ('get this figure / photo / scanned page') and explicitly distinguishes itself from the sibling fetch by routing documents, PDFs, and web pages elsewhere.

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 states exactly when to invoke fetchImage (for images to be passed to vision) and demonstrates the call shape with an explicit example. It also names the alternative tool, fetch, for non-image content, providing clear selection criteria without ambiguity.

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 indicate readOnlyHint=true, but description goes further: states 'No download' (a behavioral trait not implied by read-only), explains return format (ranked candidates with fields), clarifies empty vs error semantics, and instructs to pass the handle unchanged to fetch. This is rich context beyond annotations, though not exhaustive (e.g., no rate limiting or auth notes).

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?

Description is moderately long but dense with essential info. It opens with purpose, gives a call example, then details output, error handling, and alternative. Each sentence adds value; no redundancy. Slightly verbose but well-structured and 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?

No output schema exists, yet the description fully explains what is returned (ranked candidates with title, authors, year, kind, access) and how to use the fetch handle. It covers error semantics, empty results, and alternative routes. Given the tool's complexity and lack of output schema, this is complete for an agent to call it correctly.

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

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

Schema covers 100% of parameters (query and limit both have descriptions). The description adds value by explicitly defining query as a title or bibliographic query and explaining the output's relationship to the query (ranked candidates with fetch handle). The limit parameter is adequately described in schema, so no extra needed. Overall, description complements schema effectively.

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 states a specific verb (Finds) and resource (scholarly papers and books) with examples of acceptable queries. It explicitly distinguishes itself from search for general web queries and from fetch for retrieving documents. This leaves no ambiguity about the tool's role.

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 call example, explains when to use this tool vs search, and gives guidance on error handling (retry or fetch exact identifier). Also clarifies the workflow: findWorks returns fetch handles to be passed to fetch. This gives clear when-to-use and when-not-to-use instructions.

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

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

Annotations only provide readOnlyHint=true, but the description adds substantial behavior: returns which cached pages match rather than their text, lists the return fields, and explains the difference between empty matches and tool errors. This aligns with and extends the read-only annotation.

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

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

Three dense sentences cover target, output shape, empty-result semantics, and error semantics with no wasted words. The core distinction — local cache vs web search — 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?

As a read-only tool with no output schema, the description is complete: it specifies the return shape, how to access full content, how to interpret empty results, and what causes errors. An agent has everything required 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 coverage is 100%, so the schema already fully documents pattern, ignore_case, and max_results. The description adds a call example for pattern but does not need to compensate for any missing parameter documentation.

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

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

The description states a specific verb and resource: 'Greps the local cache of already-fetched documents', and gives two concrete questions the tool answers. It clearly distinguishes itself from siblings by emphasizing 'local cache' and explicitly noting 'the web is not searched'.

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 it ('did we already fetch X') and when not to rely on it ('the web is not searched; search or fetch first'). Empty matches are given a defined meaning, so the agent knows to fall back to another tool rather than treating it as an error.

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