ingest_directory

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

Annotations only indicate readOnly=false and destructive=false, so the description carries the behavioral burden. It adds useful context by stating that ingestion is a background-trackable job and that progress should be polled via job_status, which is not visible from the annotations or schema alone. It does not detail duplicate handling or error cases, but it covers the key async behavior.

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 two sentences and contains no filler. The core operation is front-loaded, and the follow-up guidance about polling job_status is placed at the end. Every sentence either clarifies behavior or directs the agent to the correct follow-up tool.

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 this tool's complexity, the description gives enough to confidently invoke it: it identifies the target resource, optional filters, and the asynchronous tracking mechanism. An output schema exists, so return-value details need not be explained. The only notable gap is that 'collection' is a required parameter and receives no explanation beyond its name.

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 no descriptions for parameters; the description partially compensates by mentioning local directory, optional glob include/exclude patterns, and bulk ingestion. However, it does not explain the semantics of the required 'collection' parameter beyond the tool's general intent, and it does not specify glob syntax. It adds value but does not fully compensate for the 0% schema description coverage.

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 verb ('recursively ingests'), a concrete resource ('every supported file under a local directory'), and a clear distinguishing scope: bulk directory ingestion. Given sibling tools like ingest_text, ingest_file, and ingest_url, this description makes the directory-based focus immediately obvious.

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 it: 'Use this for bulk ingestion of a folder; poll job_status for progress.' This provides a clear usage context. It does not explicitly name or exclude the sibling ingest tools, but the bulk-vs-single distinction is strongly implied.

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