Scholar Sidekick

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

Annotations already declare readOnly/openWorld/idempotent/destructive, and the description adds rich context: it is read-only and idempotent, works anonymously with key-based rate limits, mentions the 25-entry cap with excess dropped and reported, and clarifies what the tool does NOT check (source support for claims). This exceeds what annotations provide.

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

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

Though long, every sentence serves a purpose: purpose, usage triggers, input alternatives, limits, checks, return summary, and caveats. It is front-loaded with the core action and structured logically, making it dense but scannable without waste.

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

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

For a complex batch tool with 5 parameters and an output schema, the description covers all key aspects: use cases, input formats, mutual exclusion, limits, defaults, authentication, return structure, and limitations. The output schema handles detailed return shapes, so the description's brief summary is sufficient and 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 100%, but the description adds crucial semantic value beyond schemas: it explains the EITHER/OR relationship between `bibliography` and `claims`, the default for `checks`, the opt-in gating for `screenWithLlm`, and the cap behavior. This directly helps an agent choose and populate parameters correctly.

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 starts with 'Verify a WHOLE bibliography in one call — the batch counterpart to verifyCitation,' clearly stating the action, resource, and relationship to a sibling tool. It distinguishes itself by emphasizing the batch scope and lists concrete use cases, making it 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 ('when the user pastes a reference list, a .bib / .ris file, or asks to...') and contrasts with verifyCitation as the single-entry alternative. It also gives example phrasings, giving an agent clear signals for 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 declare readOnly, idempotent, and non-destructive. The description goes far beyond these by disclosing Unpaywall as the source, the DOI resolution fallback with returned doi=null/reason='no_doi', rate-limit behavior, API key requirements, and the full output shape. There is no contradiction with annotations; the description adds substantial behavioral context.

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

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

The description is long but well-structured and information-dense. It front-loads the core purpose, then covers usage, behavior, output, alternatives, and operational notes. Some details repeat schema content (accepted identifier types, no batches), but every sentence adds meaningful context or clarifies boundaries.

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 one parameter, a rich output schema, and strong annotations, the description is exceptionally complete. It covers edge cases (non-resolvable DOI), output format, rate limits, API key setup, and relationship to siblings, leaving the agent fully equipped 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?

Schema description coverage is 100% and the schema's id parameter already documents accepted identifier types and the single-identifier constraint. The description reinforces this and adds operational meaning (e.g., non-DOI inputs resolved server-side, exactly one identifier per call, loop guidance) that helps the agent avoid batching mistakes. Slight redundancy with schema, but the added context justifies a score above baseline.

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 a single scholarly work is openly accessible and where to find the best legal version.' It clearly distinguishes this tool from siblings by explicitly stating that resolveIdentifier returns metadata but not OA status, and explains the input resolution 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?

Provides explicit when-to-use guidance with example user queries ('is this open access?', 'where can I read this for free?'). It also offers clear exclusions and alternatives: single identifier per call, no comma/newline batches, loop for multiple papers, and notes that no sibling tool overlaps this functionality.

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 readOnlyHint, idempotentHint, and destructiveHint; the description adds valuable context beyond these: data provenance (Crossref updated-by mirroring Retraction Watch), input resolution behavior (DOI/PMID/PMCID/arXiv/ADS resolved to DOI; ISBN returns doi=null), batch rejection rationale, and rate limits/auth. 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 long but well-structured and front-loaded with the core purpose, then systematically addresses usage, batch behavior, output, and auth. Every sentence earns its place given the tool's edge cases, though it is more verbose than strictly necessary.

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 single parameter, a complete output schema, and rich annotations, the description covers all contextual needs: purpose, usage constraints, data source, output shape, auth, rate limits, and sibling differentiation. There are no significant gaps.

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% and the schema's 'id' description thoroughly documents accepted identifier types, batch rejection, and ISBN behavior, so baseline 3 applies. The tool description restates some of this but does not add parameter-level semantics beyond what the schema already provides.

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 a single scholarly work has been retracted, corrected, or had an expression of concern raised.' It distinguishes itself from sibling tools by explicitly stating 'No sibling tool overlaps this — resolveIdentifier returns metadata but not retraction status.'

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 the tool ('has this paper been retracted?', verifying before citing in clinical/regulatory/evidence-synthesis contexts) and provides exclusions (multi-paper audits require looping; batch input rejected). It also names an alternative (resolveIdentifier) that does not provide retraction status.

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. The description adds substantial context: auth requirements (SCHOLAR_API_KEY, RAPIDAPI_KEY), rate limits, anonymous access, retry safety, and format-specific behavior (txt uses style; others ignore it). 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 long but every sentence provides necessary information: purpose, use cases, format semantics, identifier handling, return shape, alternatives, safety, auth, and rate limits. It is logically ordered and free of fluff, earning its length.

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 complexity (10 formats, 4 params, auth, alternatives), the description covers all bases: input formats, return shape, alternative tools, rate limits, and API keys. It is even self-contained enough to guide an agent without needing to inspect the schema or 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?

Although schema coverage is 100%, the description enriches each parameter. It explains every format enum value with use cases (BibTeX for LaTeX, RIS for reference managers, NBIB for PubMed), clarifies that style only applies to txt, and details the identifier formats accepted for the text parameter. This adds significant meaning beyond the schema.

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

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

The description opens with a specific verb+resource: 'Export scholarly identifiers to a bibliography file format'. It clearly distinguishes from siblings by stating when to use exportCitation (file generation) vs. formatCitation (in-line text) and resolveIdentifier (raw metadata).

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 when-to-use guidance: 'Use when the user wants a file (.bib, .ris, .nbib, .xml, .rdf, .csv) for Zotero, Mendeley, EndNote...'. Also explicitly names alternatives: 'Use formatCitation instead when the user wants in-line citation text; use resolveIdentifier when they want raw structured metadata.'

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 well beyond the annotations: it details read-only/idempotent behavior, rate limits, API key requirements, output format semantics, metadata block structure, and style resolution (e.g., 'harvard' resolves to 'harvard-cite-them-right'). 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?

The description is lengthy but every sentence carries essential information, with the purpose and usage front-loaded. It avoids redundancy and organizes complex details (style resolution, output formats, rate limits) into a coherent flow without waste.

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 (5 parameters, output schema, many alternatives, and nuanced behavior), the description covers all aspects: return structure (text/html/items + metadata block), authentication tiers, rate limiting, style resolution, batch processing, and when-to-use alternatives. It is exceptionally 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?

Although the schema already covers all parameters at 100%, the description adds substantial meaning: style defaults, builtins vs. CSL, alias resolution, batch input format (newline/comma separated, one round trip), and the output parameter returning text/html/items. It enriches every parameter beyond schema definitions.

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

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

The description clearly states the tool formats scholarly identifiers into a finished citation with a specific style. It distinguishes from siblings by contrasting with resolveIdentifier (raw metadata) and exportCitation (bibliography file), making its unique 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 provides explicit use cases ('paste-ready citation string for a manuscript, slide, message, footnote, or in-line reference'), explicit alternatives, and even warns about style ambiguity ('Harvard' and 'Chicago' variants) requiring user confirmation before defaulting. This is exemplary 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?

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses operationally significant behaviors: authentication options (SCHOLAR_API_KEY, RAPIDAPI_KEY), rate-limit tiers, REST API caching with x-scholar-cache response header, and the ability to batch requests in one round trip. This adds substantial value over the structured 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 well-structured: purpose first, usage examples, output summary, alternatives, safety, and API details. Every sentence carries operational weight, and the front-loaded purpose sentence makes the tool's function immediately clear. Length is justified by the tool's complexity.

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 breadth (multiple identifier types, batching, API keys, and output schema), the description is remarkably complete. It covers purpose, usage, alternatives, auth, rate limits, caching, and output format without redundant explanation of return values (output schema exists). It positions the tool well relative to its siblings.

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 input schema already covers the 'text' parameter with 100% coverage, but the description enriches it by enumerating additional identifier types (WHO IRIS URL), prefix handling (PMID:, arXiv:, ISBN hyphens, https://doi.org/...), and batch semantics (comma/newline-separated, one round trip per call). This goes beyond the schema's basic listing of identifier kinds.

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+resource+output: 'Resolve scholarly identifiers to structured CSL JSON metadata (title, authors, journal, year, identifiers).' It also distinguishes from siblings by explicitly naming formatCitation and exportCitation as alternatives, 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?

The description provides explicit use cases: 'Use when the user wants raw bibliographic data to inspect, transform, or feed into another tool — not a formatted citation.' It also gives clear exclusions and alternatives: 'Use formatCitation instead when the user wants a finished citation string in a specific style; use exportCitation when they want a downloadable bibliography file.'

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, and destructiveHint=false, and the description reinforces those traits with 'Read-only and idempotent — safe to retry.' It adds substantial context: the Topaz fabrication pattern, verdict semantics, auth gating for LLM screen (400 LLM_SCREEN_FORBIDDEN for anonymous callers), and rate-limit note. These details go well beyond the annotations and meaningfully inform the agent of real-world 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 long but front-loaded: the first sentence states the core purpose. Every subsequent sentence adds unique information—detection pattern, usage triggers, parameter rules, LLM gating, return structure, verdict semantics, sibling differentiation, safety. No word is wasted; it is an appropriately sized, information-dense reference.

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 (13 parameters, multiple identifiers, gated LLM screen), the description is remarkably complete. It explains the full return object, every verdict meaning with example subtypes, authentication requirements, error codes, and idempotency. The output schema exists but is not shown in this definition; the description compensates fully by documenting the return structure and semantics.

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 every parameter baseline. The description adds value by clarifying the identifier priority order, the requirement of 'title plus exactly one identifier' (even though the schema only marks title as required), the soft-signal nature of container, and the gating of screenWithLlm. This is genuinely helpful, but not exceptional since many parameter details are already in the schema descriptions.

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

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

The description opens with a specific verb+resource: 'Verify a claimed citation against the resolved record at its identifier.' It immediately identifies the dominant AI-driven fabrication pattern and clearly distinguishes itself from resolveIdentifier by stating it is the only tool that cross-checks claimed title vs resolved metadata. This is unambiguous and differentiates from siblings.

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?

Explicit use-case guidance is provided: 'Use when the user pastes a citation and asks "is this real?" or "check this DOI".' It also states single citation per call, required fields, and explicitly names the alternative tool (resolveIdentifier) for known-good identifiers. The LLM screen usage and authentication requirements are clearly described, leaving no ambiguity about when to invoke this versus siblings.

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