jp_lit_get_record

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

Beyond the annotations, the description discloses that cache hits still update local session history and that cache misses or force_refresh create or replace local cache. It also notes the local bookkeeping write is non-destructive and clarifies that no strict distinction is made between missing content and access restrictions. The description meaningfully extends annotation data without contradicting it.

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 it is densely packed with source-specific behavior and cross-tool routing information. It front-loads the core purpose before enumerating source cases. The length is justified by the multi-source complexity, though it is near the upper limit of conciseness.

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 large source enum, an output schema, and sibling tools, the description is unusually complete: it covers per-source return scope, pid/source_id exclusivity, downstream tool availability, manual viewing guidance, cache behavior, and the batch alternative. No critical calling context appears to be 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 coverage is high at 80%, so the baseline is 3; the description adds meaningful semantics by explaining that source_id and pid are alternatives for source=ndl_digital and that exactly one must be specified. It also gives source-specific meaning for source values and clarifies that pid is used instead of source_id. While pid itself has no schema description, the tool description compensates well for that 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 states a clear verb and resource: it fetches record details from an external source without mutating it. It further distinguishes behavior per source and explicitly names the sibling jp_lit_get_records for batch retrieval, so an agent can tell what this tool is not. The opening 'external read / local bookkeeping write' clarifies the dual read/write nature beyond the generic 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?

The description gives explicit when-to-use guidance: single record lookup, with jp_lit_get_records for 2–10 pre-selected candidates. It also describes when downstream tools like jp_lit_get_text_coordinates are usable, and when they are not when source_metadata.next_digital_library.available is false. It explicitly states what is not fetched (images, IIIF, OCR, fulltext) and how to check for manual viewing alternatives.

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