Fetch a single bibliography entry by its citation ID from a CSL-YAML file, returning the full YAML block for verification or reference.
Retrieve a single bibliography entry by ID. Returns the full YAML block.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The citation ID (e.g., "BGH_I_ZR_73_79") | |
| file | Yes | Absolute path to the CSL-YAML bibliography file (required). Look for "bibliography:" in pandoc.yaml or the YAML frontmatter of .md files. |
Changes observed during successful MCP inspections.
v0.5.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. 'Retrieve' clearly signals a read-only operation, and 'Returns the full YAML block' tells the agent exactly what output to expect. It does not cover not-found behavior, but for a simple lookup this is reasonably transparent.
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 short, front-loaded sentences with no filler. The first states the operation, the second states the return value. Every word 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 simple two-parameter lookup, the description plus schema are nearly complete: required parameters are documented, the file parameter includes a concrete discovery strategy, and the return type is specified. The only notable gap is behavior on missing or invalid IDs.
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 input schema already explains both parameters, including the id example and the file discovery hint. The description adds no new parameter semantics beyond 'by ID,' so the baseline of 3 is appropriate.
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 ('Retrieve'), a specific resource ('single bibliography entry'), and a precise retrieval method ('by ID'). It also names the return format ('full YAML block'), which distinguishes it from siblings like bib:search and bib:exists.
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 this tool should be used when the agent already has a citation ID and wants the complete entry. However, it does not explicitly contrast this with bib:search or bib:exists, nor does it state what to do when the ID is unknown or when listing entries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.