vault_ingest

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

With no annotations, the description carries the full burden and it does so thoroughly: idempotency by content hash, local tesseract OCR by default, no data leaving the machine, transcription provenance flags, and a candid caveat about vision mode's fluent-but-plausible misreadings. This is exactly the safety-relevant behavior an agent needs before invoking.

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?

Three dense paragraphs with no filler: purpose first, then idempotency, then OCR behavior, then the critical vision caveat. Each sentence carries information an agent needs for correct and safe invocation.

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 moderate complexity and that an output schema exists, the description covers the behavioral decisions that matter: what gets skipped, how scans are handled, what happens to extracted text, and when vision should be opted into. Nothing material to calling the tool correctly is left unexplained.

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 documents three of four parameters; the description adds meaningful meaning beyond it, especially for ocr (local vs vision trade-offs, privacy, transcription flagging) and force (contextualized by the idempotency-by-hash behavior). Only recursive lacks any prose, but the phrase 'under a directory' and its default mitigate the 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 opening line uses a specific verb set — 'Extract, chunk, and store' — with a scoped resource ('every supported file under a directory'). This makes the batch-ingest role immediately clear and distinguishable from the read/search siblings like vault_search and table_read.

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 the use case (bulk ingestion of a directory into the vault) and explains key modes, but it never explicitly states when to choose this tool over an alternative or when not to use it. No sibling is named as a fallback, so the agent must infer routing from the tool name and opening verb.

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