Update Page

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

Annotations already declare destructiveHint=true, so the agent knows this is a mutation. The description adds no extra behavioral context—e.g., whether it performs a full replacement or partial merge, whether unspecified fields are reset, or any side effects on related objects. With the annotation covering the destructive nature, the description still fails to disclose update semantics beyond the bare verb.

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, concise sentence with no filler. It front-loads the core purpose and does not waste words. However, it is somewhat under-specified, which is a completeness concern rather than a conciseness one—structurally it's efficient.

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 mutation tool with 6 parameters, 2 required, and a destructive hint, the description is too minimal. It does not explain whether updates are partial or full, doesn't clarify that course_id and page_url are the identifiers (though required in schema), and gives no operational guidance. The presence of an output schema reduces the need to describe return values, but the description still lacks essential behavioral detail for an agent to safely invoke 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 description coverage is 100%, so the schema fully documents each parameter. The description does not add any additional meaning about how parameters relate (e.g., that course_id and page_url identify the target page, or that body/title/published are optional and only updated if supplied). It simply says 'update', which adds nothing beyond the schema. Baseline 3 is appropriate.

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 clear verb and resource: 'Update an existing wiki page.' It correctly distinguishes from the sibling create_page (new pages) and delete_page (removing pages) by emphasizing 'existing'. However, it doesn't enumerate which fields can be updated (title, body, published, etc.), which is a minor gap for an agent deciding if this tool fits.

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 no explicit guidance on when to use this tool versus alternatives. It does not mention create_page for new pages or delete_page for removals, and offers no conditions or exclusions. The only context is the word 'existing', which weakly implies it's for already-created pages, but there's no proactive routing.

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