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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds value by disclosing the returned content (membership plus quota) and the rolling-window semantics, which explains why idempotentHint=false for a read. It omits auth requirements and rate-limit 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?

Two sentences, no filler. The capability is front-loaded and the usage cue follows, so a scanning agent gets both the what and the when in minimal reading time.

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 present, the description need not enumerate return fields, and it does note the two key outputs anyway. For a no-required-parameter read-only tool this is essentially complete, with only auth/rate-limit context 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 100% and there is only one optional parameter (timeout_seconds), so the schema carries the semantics. The description adds no parameter-level information. Baseline 3 applies when the schema does the heavy lifting.

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 ('Show') and two concrete resources: the account's membership and its remaining fast downloads in a rolling window. An agent can immediately distinguish this status/quota tool from the sibling download and search tools without opening any 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?

Explicitly gives the trigger condition: 'Check it before downloading many files.' That is actionable guidance tied to the sibling download tools. It stops short of naming alternatives or stating when not to call it (e.g., it is cheap/safe to call anytime), so it is clear context rather than a full when/when-not rubric.

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 declare the mutation/openWorld profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=true). The description goes well beyond that, disclosing the resolution flow (DOI to hash), the local-reuse behavior when the full MD5 matches, the fallback of downloading under a unique name, and that downloads_left is omitted on reuse — exactly the operational detail an agent needs.

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?

Front-loaded with the identifier constraint, then the resolution/reuse flow, then the parameter caveat. Dense but each clause carries information; the only cost is that the third sentence reads as a run-on, slightly hurting scannability.

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 download tool with a full output schema, the description covers everything an agent needs: identifier rules, resolution and reuse behavior, naming effects of optional params, and the fact that downloads_left is conditionally present. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds value by tying title and format to the reuse path ('control a new file's name'), implying they are ignored when an existing file is reused. That is meaningful semantics not spelled out in the schema.

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

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

States a specific verb and resource ('Download a selected paper') and immediately constrains the identifier to 'exactly one of doi or hash'. Combined with the word 'paper', an agent can distinguish it from the sibling book_download and from article_search without opening any 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 clear selection conditions: use exactly one of doi or hash, and the hash field accepts either a bare MD5 or an Anna's Archive /md5/ page URL. It does not explicitly name a sibling alternative (e.g., book_download for non-article items), so it stops short of full when/when-not routing, but the implied scope is unambiguous.

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 the safety profile (readOnly, openWorld, non-destructive), so the description's job is to add context — and it does: DOI lookup returns a single paper, keyword search returns one page, and include_stats triggers a per-file statistics lookup. It does not mention auth or rate limits, but it adds meaningful behavioral detail beyond the structured hints.

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?

Front-loaded with the two core modes, then scoping options, then the downstream workflow hint. Every sentence carries information, though the closing 'compare metadata' sentence is advisory rather than definitional.

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 16-parameter search tool with no output schema, the description covers return cardinality, the stats side-effect, and the download-comparison workflow. Pagination behavior and result shape are only lightly touched, leaving a small gap.

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 100%, so the schema already documents all 16 parameters. The description restates include_stats and alludes to hashes, but adds little syntax or format detail beyond what the schema provides — the baseline of 3 fits.

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?

It states specific verbs and resources — DOI lookup and keyword search over journal articles — and clearly delineates the two modes. The 'article' scope implicitly separates it from book_search, but no sibling is named, so the differentiation is inferential rather than explicit.

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 clear context for choosing between the two modes (DOI vs keyword) and notes that include_stats and downloadable_only shape results. It stops short of naming alternatives like metadata_search or book_search, so there is no explicit when-not 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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds useful context about record contents, including volatile data (problems reported, download and quality counts), which loosely explains the idempotentHint=false. However, it says nothing about error behavior for missing hashes, auth needs, or rate 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, front-loaded with the core action, and the identifier-source sentence is placed last where it is most actionable. The field enumeration is slightly long, but each listed item is real content rather than 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?

An output schema exists, so return values need not be explained, yet the description still orients the agent on what the record holds. Combined with the id-sourcing guidance, an agent has enough to call the tool correctly; only edge-case behavior (invalid/expired hash, missing record) is unaddressed.

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 100%, so both parameters (id and timeout_seconds) are already fully documented in the schema. The description restates the id sources but adds no syntax, format, or failure-mode detail beyond what the schema provides, so the baseline of 3 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?

States a specific verb and resource ("Get the full record") and then enumerates exactly what the record contains: identifiers, edition, year, description, subjects, problems, counts. It is clearly the detail-lookup counterpart to the sibling search tools, so an agent can tell it apart from book_search/article_search/metadata_search without opening any 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?

Explicitly says the tool takes a hash from book_search or article_search, or an id from metadata_search, which tells the agent this is the follow-up call after a search. It gives clear context but no explicit exclusions or when-not-to-use conditions, so it stops short of a 5.

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

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

Goes well beyond annotations by disclosing the local-reuse behavior (returns an existing file when the full MD5 matches), verified downloading under a unique name, that path and bytes are returned, and that downloads_left is omitted on local reuse. This is the kind of behavioral detail an agent could not get from the structured fields 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?

Front-loads the core action and inputs in the first sentence, then layers return behavior and the format caveat. Every sentence carries distinct 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?

An output schema exists so return values needn't be enumerated, yet the description still usefully characterizes the response and its conditional field. It omits failure modes (unavailable book, exhausted quota, timeout expiry), which is the only meaningful gap for a tool with retries and a 24h max timeout.

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 100%, so the baseline is 3. The description restates the hash input forms and the format-does-not-convert rule already present in the schema, but adds no syntax or edge-case detail (e.g. timeout behavior or format inference rules) beyond it.

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 (download) and resource (the selected book) and specifies the exact input forms accepted (32-char MD5 or Anna's Archive /md5/ page URL). This clearly separates it from siblings like article_download and book_search without needing schema inspection.

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 'the selected book' implies a prior selection step (e.g. book_search/book_details) must happen first, but no alternative tool is named and no explicit when-not condition is given. Usage is inferable but not spelled out.

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, openWorldHint, idempotentHint=false and destructiveHint=false, so safety is covered. The description adds real behavioral context: results are one page, each page carries hash/format/year/fast_download/metadata, and include_stats triggers an extra statistics lookup for returned hashes.

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 purpose before filters, return shape and follow-up routing. Dense but each sentence carries information; 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 16-parameter read-only search tool with an output schema and 100% schema coverage, the description supplies everything an agent needs: scope, filter axes, return shape, the include_stats side effect, and where to route a chosen hash. Return-value details are correctly delegated to 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 100%, so the schema already documents all 16 parameters with formats, defaults and exclusion syntax. The description echoes the filter categories (format, language, content type, source, year, sort) and include_stats but adds no syntax or meaning beyond the schema, so baseline 3 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?

States a specific verb (search) and resource (books, textbooks, manuals, standards) plus the matching dimensions (title, author, topic) and filter/sort axes. It is clearly distinguishable from article_search and metadata_search siblings by naming book-specific concepts and the hash/download workflow.

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 next-step routing: pass a selected hash to book_download, or to book_details for ISBNs, edition and file problems. It does not state when NOT to use this tool (e.g. use article_search for DOIs), so it falls short of full when/when-not 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=true, destructiveHint=false and openWorldHint=true, so the safety and external-call profile is covered. The description adds genuinely new behavioral context beyond those hints: results span multiple third-party catalogs and include records with no downloadable file, which sets expectations for return content. It does not mention rate limits or retry behavior, though the schema's timeout_seconds parameter partially 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 sentences, each carrying distinct load: what is searched, the workflow handoff, and the details handoff. The most decision-relevant information (catalogs, no-downloadable-file scope) 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?

All 11 parameters are covered by a 100% schema, an output schema exists so return values need no explanation, and annotations cover the safety profile. The description supplies the workflow positioning against book_search and book_details that the structured fields cannot express.

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 100%, so every parameter is already documented in the schema; baseline is 3. The description only reinforces a couple of fields indirectly (query by ISBN or title, id-based lookup for book_details) and adds no syntax or format detail beyond what the schema states.

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

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

States a specific verb and resource ('Search library catalogs ... for books') and names the concrete sources (Open Library, WorldCat, ISBNdb, Goodreads, Google Books). It explicitly separates itself from book_search by noting it covers books with no downloadable file, so an agent can pick correctly without opening either 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 routing: use this to find ISBNs/editions/publication details, then use book_search by ISBN or title for files, and pass an id to book_details for identifiers. Both the intended step in the workflow and the alternatives are named, leaving nothing to inference.

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