Swagger: Update Document

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

The description adds a non-obvious behavioral constraint: the combination of type='html' and source='internal' is not allowed, while external source documents are editable via API only. The annotations already convey mutation and destructiveness (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the description's additional restrictions justify a solid but not maximal score.

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 first sentence is crisp and the toolset label adds orienting context, but the parameter block replicates the schema's descriptions, adding redundancy rather than new value. It is still structured and readable, so it earns a middle score.

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?

With an output schema present and all four parameters documented at 100% coverage, the description covers the key constraints: supported type/source combinations and internal vs external editing. The only minor omission is guidance on how to obtain a documentId, but sibling get_document tools make that inferable.

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%, and the description's parameter section repeats the schema text almost verbatim rather than adding new meaning. It accurately restates the content/type/source semantics and enum options, so the baseline of 3 applies.

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 names a specific operation ('Update'), a specific resource ('existing document'), and the exact scope ('content or source'), and lists the supported HTML/Markdown types. This clearly marks it as different from create/get siblings like swagger_create_documentation_page and swagger_get_document, even without naming them.

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 type/source parameter notes explicitly state that documents with type 'html' and source 'internal' cannot be edited via API, and that only 'html' + 'external' and all 'markdown' combinations are supported. The source parameter also names the alternative ('portal UI') for internal editing, so an agent knows when to use this tool and when not to.

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