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

Annotations already declare non-read-only, open-world, non-destructive, but the description adds substantial behavior beyond them: per-post cost ($0.02 from balance), idempotent reschedule on repeat calls for the same file, re-render vs original-bytes publishing semantics, per-platform account fallback logic, and the access-token requirement. It does not disclose partial-failure behavior when one platform fails, which keeps it from a 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?

Purpose and source options are front-loaded, then semantics, then constraints and cost. Every sentence carries actionable information (pricing, idempotency, auth, format). It is dense and long, but no clause is pure 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?

For a mutation tool with 8 parameters, 50% schema coverage, and no output schema, the description supplies the missing operational context: auth, cost, idempotency, scheduling format, and account selection. The main gap is failure/error semantics (what happens if scheduling partially fails across platforms or the token lacks scope), which an agent invoking a paid, multi-platform mutation would benefit from.

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 only 50%, so the description must compensate and largely does: scheduledAt format and a concrete ISO-8601-with-timezone example, publishNow: true meaning immediate post, accountIds source plus the 'each must be on one of the platforms' constraint, and the render true/false consequence (re-render vs original bytes). fileId and platformConfigurations are left to the schema. Clear value added over structured fields.

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?

Opens with a specific verb+resource (schedule a finished static Picorn file or an existing video) and immediately distinguishes the two accepted sources, explicitly naming picorn_posts_upload_video for videos. An agent can tell this apart from picorn_posts_list, picorn_posts_cancel, and picorn_render_svg 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?

States when to use it (finished static file or existing uploaded video) and routes to alternatives: accountIds must come from picorn_account_status, video must come from picorn_posts_upload_video, and ownership is verified via picorn_files_list. Also distinguishes scheduling from immediate publishing via publishNow. Explicit when/where conditions throughout.

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