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

Goes well beyond the annotations: it explains that PUBLISHING means in-flight, that a cut-off call must be retried with the same operation_id to avoid duplicates (the mechanism behind idempotentHint), and that Instagram caps video at 300 MB (100 MB for stories) as a platform condition, not an app error. It even prescribes how to report a size failure to the user and notes other networks still succeed with the original file. This is exactly the kind of operational context annotations cannot carry.

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: the core action and scheduling condition come first, then the usage gate, then status/retry semantics, then the platform limit. The final sentence about how to phrase an Instagram failure is user-facing guidance that stretches the definition slightly, but it is actionable and not redundant.

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 12-parameter, nested, destructive, open-world publishing tool with no output schema, the description covers the highest-risk unknowns: idempotent retry, what the PUBLISHING status means, how to verify results via get_post, and cross-platform size behavior. Format-specific rules (carousel limits, TikTok draft) are left entirely to the schema, which is acceptable given their enum descriptions.

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 58% across 12 parameters, and the description only touches scheduled_for (scheduling), operation_id (retry semantics), brand ('marca acordada') and media size limits for media_ids. It adds a real constraint not present in the schema (Instagram video weight limits), but the nested targets, tiktok and youtube objects get no added meaning beyond their schema descriptions.

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 pair: it creates the post and sends it to publish across all selected destinations in a single action, or schedules it when scheduled_for is in the future. The phrase 'en una sola acción' implicitly contrasts with a separate create-then-publish flow, but it never names the obvious siblings (create_post, publish_post, publish_now, create_and_publish_carousel), so an agent must still infer the boundary.

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?

'Úsala solo cuando el usuario pidió publicar o programar, con marca, redes y texto acordados' gives a clear gate condition plus prerequisites (brand, networks, copy already agreed). It also adds a post-call verification rule (confirm with get_post before claiming success). Missing an explicit statement of when NOT to use it in favor of create_post/publish_post.

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