Doco Edit Concepts

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

Annotations already mark the operation as destructive and not read-only. The description adds valuable behavior beyond annotations: automatic ETag reading, If-Match header sending, and idempotency-key generation for each write. These details alert the agent to optimistic concurrency and retry expectations. There is no contradiction with idempotentHint=false because generating a key does not assert tool-level idempotency.

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 one dense, front-loaded sentence listing all operation types, followed by one sentence of critical client behavior. Every clause carries information and there is no padding or repetition.

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 13-parameter, 7-action destructive write tool, the description provides the high-level operation map and concurrency/idempotency behavior, while the output schema, annotations, and per-parameter schema descriptions cover the rest. The main remaining gap is explicit action-to-parameter guidance, but the schema field names and descriptions are sufficiently suggestive for an agent to fill it.

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 coverage is 100%, so the baseline is 3, but the description goes beyond the enum names by explaining the semantic groups: create, update, source/relation addition, merge, and candidate accept/reject. It still does not map each action to the specific required parameters (e.g., merge needs target_concept_id), but the schema parameter names partially cover that.

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 states a specific verb ('unified write') and a specific resource ('explicit concepts'), then enumerates the exact operation categories: create, update, add sources/relations, merge, and accept/reject candidates. This clearly identifies the tool as the concept-mutation entry point and differentiates it from read/search/translation siblings such as doco_get_tree or doco_search.

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 word 'unified' implies this is the intended single entry point for explicit concept writes, and the action list implies the supported cases. However, the description never says when to prefer this over overlapping siblings like doco_create_relation or doco_batch_edit, nor does it mention any exclusion conditions.

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