bib:add

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It covers several important behaviors: CSL-type validation, duplicate-ID checking, creating a .bak backup before writing, and returning the created YAML block. However, it does not specify what happens when a duplicate ID is found or when validation fails, leaving failure semantics unclear.

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 three compact sentences with no filler. The core action is front-loaded in the first sentence, followed by behavioral guarantees and the return value. Every sentence contributes meaningful information.

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?

The description covers purpose, validation behavior, backup side effect, and return value, which is strong for a tool with no annotations and no output schema. However, it omits failure behavior on duplicate IDs, invalid required fields, and whether the target file must already exist or may be created. These are meaningful gaps for a mutation tool.

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 the file, entry, and style parameters thoroughly. The description adds context about CSL-type validation and duplicate checking, but it does not clarify parameter-specific details like file path resolution or the exact effect of the optional style parameter, which keeps it at the baseline 3.

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 is explicit: 'Add a new bibliography entry' uses a specific verb and resource, and the word 'new' distinguishes this from sibling operations like update, delete, get, and exists. It also states the key behaviors—validation, duplicate checking, backup creation, and return value—so an agent can identify the tool's role immediately.

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 clearly states the intended use: creating a new bibliography entry, not updating or deleting one. It communicates the context of adding entries with validation and duplicate-ID checks, but it does not explicitly mention alternatives like bib:update for existing entries or bib:validate for pre-validation, so no exclusions are stated.

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