Amend a page

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

Annotations only signal non-read-only, non-idempotent, non-destructive. The description adds substantial behavioral context beyond that: it commits and pushes to the tracked branch to publish, the message becomes the commit title, and pages are never deleted. This fully discloses the side effects.

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 dense sentences, each earning its place: the core action plus commit/publish behavior, then the two call modes and the non-deletion guarantee. No filler and no repetition 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 side-effecting tool with no output schema, the description covers the main outcomes (commit, push, publish) and the non-destructive guarantee. It leaves some gaps — such as error behavior when find does not match or when a path is missing — but the essentials an agent needs to call it correctly are present.

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 100% and each parameter already has a description. The description adds value by making the either/or relationship between content and edit explicit and by clarifying that find must match exactly once, which is not fully conveyed by the schema alone.

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 ('Create or change one markdown page under content/') and covers the two modes (content vs edit). It is clearly distinguishable from the read-only siblings kb_search, kb_read, and kb_list.

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 provides clear context for use: it is the write/publish tool among read siblings, and it explains when to pass content vs edit. However, it never explicitly names alternatives or states when not to use the tool, so it stops short of a full 5.

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