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

Annotations cover the safety profile (destructiveHint=true, readOnlyHint=false, openWorldHint=true), and the description adds real behavioral context beyond them: the resulting state (status=canceled, record kept), the 409 rejection paths, the deliberate non-effect on pending auto-recycle entries, and retry semantics. The retry-safety claim is conditioned on the idempotency_key, which qualifies rather than flatly contradicts idempotentHint=false, but the tension means it is not a clean 5.

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?

Four tight sentences, each carrying distinct information: effect, rejection conditions, sibling-tool boundary, and retry behavior. The primary outcome is front-loaded with zero filler.

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, the description must carry behavior, and it does: state change, error path, side-effect scope, and retry semantics. Minor gaps remain, such as whether workspace_id is required for this mutating call given the schema's 'required when creating content' note, and what the response body contains.

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%. The description explains the meaning of the most consequential parameter, idempotency_key (same key returns the original result), but says nothing about brand_id, workspace_id, or the body/query overrides, and the target post id is only referenced anaphorically as 'the post'. At mid coverage this is adequate but not compensating.

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 (cancel a post) and the exact effect: the post will not publish, status becomes canceled, record retained. It explicitly distinguishes itself from aidelly_cancel_scheduled_post, which also cancels pending auto-recycle entries, so an agent can pick correctly without opening either 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?

Gives explicit when-not conditions (posts already completed, failed, or canceled are rejected with 409) and names the alternative tool with the condition that selects it (aidelly_cancel_scheduled_post also cancels pending auto-recycle entries). Nothing about routing is left to inference.

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