medeval_patch_document_revision

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

Annotations already indicate a write operation (readOnlyHint=false) and non-destructive nature (destructiveHint=false). The description adds the crucial behavior of appending rather than overwriting, which clarifies that it does not modify existing revisions and preserves history—a trait not fully captured by the annotations. However, it does not disclose error behavior on optimistic-lock conflicts or any side effects beyond the append guarantee.

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 a single, compact sentence that front-loads the action and its key guarantee. Every word contributes meaning—'append' and 'never overwrite' are specific and avoid redundancy. There is no filler 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?

Given the complexity of five required parameters, no schema descriptions, and no explanation of the operations array or instruction semantics, the description is grossly incomplete. The output schema exists, but the agent still needs to know how to form a valid patch request, what base_revision_id represents, and what happens on conflict—none of which are addressed. This falls far short of what a mutation tool with this parameter count requires.

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 input schema has 0% coverage, meaning no parameter descriptions exist, and the tool description makes no attempt to explain the five required parameters (workspace_id, document_id, base_revision_id, operations, instruction). The description is entirely silent on what 'operations' entails or the role of 'instruction', leaving the agent with no semantic guidance for constructing valid calls.

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 action ('Append one optimistic-lock revision') and a resource (revision), and clearly distinguishes itself from read-only siblings like list_document_revisions and read_document_revision by emphasizing the write-append nature. The constraining clause 'never overwrite revision history' further clarifies its unique purpose among the revision-related tools.

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 implies a usage scenario (creating a new revision with optimistic locking) but does not explicitly state when to use this tool versus alternatives such as read or diff tools. The constraint 'never overwrite revision history' suggests a safe append operation, but there are no direct exclusions or alternative tool references, leaving the agent to infer the appropriate context.

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