insert_text

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

With no annotations provided, the description discloses the key asynchronous behavior (indexing happens later; returns a track_id to poll). It does not mention side effects or authorization, but for a non-destructive text insertion this is adequate.

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?

Two concise sentences that front-load the main action and then provide the essential follow-up instruction. No filler or redundant content.

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 fully explains the call and the next step (polling get_track_status), and the existing output schema covers the track_id return. The only missing piece is explicit mention of when to prefer insert_texts, which is already captured in usage guidelines.

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 both parameters are already documented (text non-empty; file_source for attribution). The tool description adds no parameter-level meaning beyond 'single piece of raw text', matching the baseline for fully covered schemas.

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 names the specific operation 'Insert a single piece of raw text into the knowledge base' with the explicit resource (knowledge base) and distinguishes it from insert_texts by specifying 'single' and from file uploads by 'raw text'.

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?

It gives clear workflow context: use for raw text, and after the call poll with get_track_status to await indexing. It does not explicitly enumerate alternatives like insert_texts for multiple pieces, so it stops short of a 5.

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