Create document

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

With no annotations, the description carries the full behavioral burden, and it does disclose the highest-value traits: documents are published (public) by default, drafts are opt-in via publish=false, and collectionId is mandatory. It omits permission requirements, whether published posts are externally visible, and error behavior, which are meaningful gaps for a write tool without annotations.

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?

Three tight sentences, front-loaded with the core action, then defaults, then the required-parameter dependency and optional nesting. No filler and no restatement of the title.

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 5-parameter create tool with no output schema and no annotations, it covers the essentials an agent needs to invoke correctly: required inputs, default visibility, draft escape hatch, sourcing of collectionId, and nesting. It would be complete at 5 if it mentioned auth/permission prerequisites or that the new document's id is what subsequent update_document calls need.

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 already 100%, so the baseline is 3. The description adds genuine value beyond the schema by telling the agent where collectionId comes from ("use list_collections") and by surfacing the publish default as a decision point rather than a passive field default; the remaining field mentions repeat schema text.

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?

States a specific verb and resource ("Create a new Outline document from markdown") and immediately adds the two behavioral facts that matter most: default published state and the required collectionId. It is clearly the creation tool among the siblings, though it never explicitly contrasts itself with update_document/move_document, so it stops short of full sibling differentiation.

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?

Gives concrete decision context: pass publish=false to save a draft, retrieve collectionId via list_collections, and optionally nest via parent. It names an alternative tool (list_collections) with the condition that selects it, but offers no guidance on when to prefer this over update_document or when creation would fail (e.g., missing permissions, duplicate names).

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