document_ingest

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

With no annotations provided, the description carries the full burden. It discloses the indexing behavior, the separate reference bank, the cosine similarity retrieval, source defaulting to filename, server-side path resolution with the Docker caveat, and the return format. It does not explicitly state that it is a write operation, but 'index' implies mutation. Overall, good transparency for a tool with no annotations.

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 compact and well-structured. It covers what, where, parameter semantics, a critical environment caveat, and the return value in a few sentences. Every sentence provides value, with no redundancy or filler.

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 is largely complete for a two-parameter tool, covering purpose, parameter details, environment constraints, and return values. It lacks explicit mention of error conditions or prerequisites (e.g., file existence, permission requirements), which would make it fully complete. Given no annotations and an output schema that likely specifies the return, the description handles the main context well but leaves a few edge cases unaddressed.

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 0%, so the description must compensate. It does so effectively: 'source defaults to the filename' clarifies the optional parameter, and 'path resolves on the SERVER's filesystem' with the Docker note explains the required parameter. The supported file types also add meaning to 'path'. This is excellent parameter-level guidance.

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 the tool's function: 'Index a file (.txt / .md / .pdf) into the reference bank.' It specifies the resource (files), the action (index), and the destination (reference bank), and distinguishes it from conversational memory tools. This is a specific and unambiguous purpose.

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 provides clear context on when to use it: for background documents (papers, manuals, codebases) kept apart from conversational memory. It implies that for conversational memory, other tools should be used, but it does not explicitly name an alternative. The Docker path caveat offers practical usage guidance, but explicit 'when not to use' is absent.

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