add_source

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

No annotations are provided, so the description carries the full behavioral burden. It discloses auto-backup semantics, the meaning of backup=False, atomic validated saving, and that the tool refuses documents open in Word. This gives an agent realistic expectations about persistence, safety, and failure conditions.

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-organized: purpose first, then key parameter conventions, workflow guidance, and finally side-effect/failure behavior. Every sentence earns its place, and the structure keeps the dense content scannable.

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 21 parameters, no annotations, and no per-parameter schema descriptions, the description covers the critical context: what the tool adds, how it relates to citation workflow, prerequisite detection, backup behavior, and an important failure condition. The output schema exists, so not explaining return values is appropriate.

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 schema has 0% parameter description coverage, but the description provides meaningful semantics for the most important parameters: tag, source_type, authors/editors, and backup. It does not individually describe every bibliographic field, but names like volume, issue, pages, and publisher are self-explanatory, and the description compensates for the schema's lack of detail on the highest-risk parameters.

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 a specific action ('Add a Word-native bibliography source to the document store') and immediately differentiates itself from related tools by naming insert_citation and insert_bibliography as the downstream consumers. This distinguishes add_source from sibling citation tools without requiring the agent to inspect their schemas.

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 explicitly tells the agent when to use this tool versus alternatives: cite with insert_citation, render with insert_bibliography, and run detect_citation_system first on unfamiliar documents. It also warns about the consequence of mixing citation systems, giving an agent clear decision criteria.

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