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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the bar is lower. The description usefully names the external targets (WordPress/Shopify) and explains the idempotency contract for clientRequestId, but it never says what the destructive hint actually means here — whether publishing can be undone, what happens to the article on failure, or that credits are consumed.

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?

Three short sentences, zero filler, with the target scope and the retry rule both front-loaded. Every sentence carries actionable information.

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 destructive, open-world, credit-consuming mutation with no output schema, the definition covers the safety caution and the idempotency rule but omits what a successful call returns, how long publishing takes, and what a partial failure looks like. Adequate, but a caller still has gaps to guess at.

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 a moderate 67% and the schema already documents credits, pricingVersion, takeSiteLive and clientRequestId. The description only reinforces clientRequestId and restates the takeSiteLive caution; articleId and destinationId are undocumented in prose, so no meaningful value is added beyond the schema.

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 plus resource ('Publish an approved article') and names the three destinations (saved page, WordPress site, Shopify shop), which separates it from sockets like soclo_page_publish and soclo_post_publish. It does not explicitly name a sibling alternative, so it stops short of a 5.

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?

'Publish an approved article' implies the approve step is a prerequisite, and the retry advice plus 'Do not make the whole page public unless the owner asks' give conditional guidance. However, the description never routes the agent between this tool and the clearly related soclo_articles_approve, soclo_articles_publish_quote, or soclo_articles_check_quote calls.

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