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

Annotations declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so safety framing is partially covered; the description still adds real context by stating the result is a DRAFT (not published) and that all platforms share one post_id that grouping, scheduling and analytics depend on. The ungroupable-post_id warning is a genuine consequence the annotations cannot express. It stops short of covering retry/idempotency behavior, which is only in the schema.

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?

Front-loaded with the verb and state, then layers the multi-platform rule, the anti-pattern, the sibling alternatives and the tag hint. Dense but readable; the shared-post_id point is made twice (grouping benefit, then splitting penalty), which is defensible emphasis but costs a little tightness.

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 deeply nested, multi-platform creation tool with an output schema, it covers everything the agent needs to call correctly: account selection, platform field rules via postey://platforms, content limits via validate_post_content/max-length enforcement, multi-platform batching, tags and sibling alternatives. Return values are covered by the output schema, so no gap remains.

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?

The single top-level 'request' param carries no schema description (0% reported coverage), but the description compensates by explaining account_id provenance and confirmation, the additional_platforms pairing and uniqueness constraint, and inline tag get-or-create with exact casing. It also provides a concrete call example, which the schema cannot.

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, resource and state ('Create a new DRAFT post'), immediately distinguishing it from publish_draft and update_post. It also explicitly positions it against convert_post_content, add_tag and validate_post_content, so the agent can tell it apart from siblings without opening any schema.

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?

Explicit routing rules: use convert_post_content only for auto-adaptation, not multi-platform creation; pass tags inline instead of calling add_tag; read account_id from postey://accounts rather than guessing. It also gives the positive condition (one call per topic across platforms) and the negative consequence of splitting into separate calls.

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