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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds only the word "draft", without saying whether published pages are readable, what the response contains, or what happens when the path does not exist.

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?

A single short sentence with no filler and the editing intent placed up front. Its brevity tips into under-specification rather than verbosity, but there is no wasted wording.

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 no output schema and an undocumented "path" parameter, the description should explain what reading a draft returns (raw content, structured blocks) and how paths are formed. It does neither, leaving key call-time details unaddressed.

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 50%: "site" is documented in the schema, but "path" has no description anywhere. The description says nothing about either parameter, so it does not compensate for the undocumented format of the file path (relative? slug? extension?).

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?

"Read a draft file (to edit it)" gives a verb and a resource, but the resource is described as a "file" while the name/title say page, and it never distinguishes itself from siblings like list_pages, edit_files, or write_page. An agent can guess the intent but not the exact scope.

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 parenthetical "(to edit it)" implies this is the read-before-write step, but no explicit when-to-use, when-not, or alternative (e.g. list_pages for discovery, write_page for saving) is given.

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