knowl_ingest_atoms

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

Annotations provide only openWorldHint=false, so the description carries nearly the full burden of behavioral disclosure. It does so well: it reveals this is a write operation, discloses that superseded items are 'retired in the same write,' and describes the result shape ('reports each atom individually, including any overlapping item left active and the exact call to retire it'). It falls short only of disclosing idempotency, partial-failure behavior, or concurrency semantics.

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 every sentence earns its place: core purpose, content exclusions, timing, routing preference, supersedes workflow, and result reporting. The supersedes sentence is somewhat long and could be tightened, but there is 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?

For a write tool with 3 parameters and a heavily documented atoms schema, the description covers the operational essentials: what to store, when to ingest, the correction/retirement workflow, and the high-level result shape. The exact result structure is described only vaguely and the 50-item batch limit is left to the schema, but nothing critical for correct invocation is missing.

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 the baseline is 3. The description adds value beyond the schema by explaining when and why to set supersedes ('so it is retired in the same write; never leave two active items asserting different values for the same thing') — conditional usage guidance the schema's field-level description does not convey. This lifts it above baseline.

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 sentence states a specific verb and resource: 'Store pre-extracted structured knowledge atoms from an MCP client.' It further clarifies scope by listing the accepted categories (facts, decisions, constraints, architecture, state, skills) and explicitly excluding raw chat transcripts. The claim 'This is the preferred MCP ingestion path' differentiates it from the sibling knowl_ingest and knowl_store without needing to open 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 gives explicit content rules ('Do not store raw chat transcripts; extract durable facts...') and timing guidance ('during execution or after each completed subtask'). It also instructs when to set supersedes for corrections. However, it does not name alternative tools or state conditions under which another tool should be chosen instead, so the guidance is strong on content but weaker on explicit exclusion.

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