write_outlineSave a new page-by-page outline for a deck (pages written for the old one are dropped). The reply carries PAGE 1'S BRIEF; each submit_page reply carries the next page's.
| Name | Required | Description | Default |
|---|---|---|---|
| tone | No | The register, e.g. 'confident, technical, CTO-to-CTO'. | |
| pages | Yes | ||
| deck_id | Yes |
Changes observed during successful MCP inspections.
Input schema / properties / guest_tokenRemoved value: -{
- "description": "Only for a deck created WITHOUT an account: the guest_token create_deck returned.",
- "maxLength": 80,
- "type": "string"
-}Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description earns credit for specifying WHAT is destroyed: 'pages written for the old one are dropped.' It also discloses the unusual reply contract, that the reply carries page 1's brief. It does not mention authorization or irreversibility beyond the drop, but the key destructive behavior is named.
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?
Two sentences, front-loaded with the action and the destructive consequence, then the reply behavior. It is appropriately sized, though the second sentence is slightly cryptic without knowing submit_page.
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 destructive write tool with no output schema and only 33% schema coverage, the description covers the destructive behavior and a key reply detail, but it leaves deck_id and tone unexplained and does not describe the full page object requirements. It is adequate but with clear gaps.
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 33%, so the description must compensate, but it says nothing about deck_id, tone, or the shape of pages. The schema describes many nested fields, but neither the description nor the schema explains the top-level page array semantics. The reply contract is the only parameter-related value added.
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 and resource ('Save a new page-by-page outline for a deck'), and names the consequence for existing pages. It is distinguishable from siblings like submit_page and edit_page.
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 when the tool is used (creating a new outline) and that pages from the old outline are dropped, but it does not explicitly contrast with alternatives such as edit_page or submit_page, nor does it state whether it requires a prior create_deck.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.