edit_post

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

With no annotations at all, the description carries the full behavioral burden. It does disclose two meaningful traits: the operation is owner-scoped ('your own post') and requires authentication, which is more than nothing. But it omits whether this is a full replacement or partial update, whether the edit is reversible, and what the response contains.

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 the core action front-loaded and no wasted words. It is efficient, though the extreme brevity here reflects under-specification as much as good editing.

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?

A mutation tool with no annotations, no output schema, and 0% parameter documentation needs considerably more than one clause. Auth and ownership are covered, but return behavior, update semantics, and parameter formats are all absent.

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 0% for both parameters, so the description must compensate and does not. It only loosely implies a post identifier and new content; there is no guidance on post_id format or whether content replaces or appends to existing 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?

The description gives a specific verb and resource ('Edit ... post') and adds an ownership scope ('your own') that separates it from generic post tools. It is clear, but it never names a sibling such as edit_comment or create_post to disambiguate further.

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 '(requires user auth)' is a real precondition and implies the caller must be authenticated as the post owner. However, there is no when-not guidance, no mention of alternatives like delete_post or create_post, and no statement about which posts qualify for editing.

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