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

The annotations declare destructiveHint=true and readOnlyHint=false, so the agent already knows this is a mutation. The description adds valuable nuance: setting status to published here records no URL, the scheduledFor holds a 'stalled at ready_to_publish' flag until the schedule lapses, and publish auto-detect behavior is described. This goes beyond the annotations and helps avoid side-effect pitfalls.

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?

The description is dense but not wasteful. The first sentence states the core purpose, the second sentence addresses the key alternative, and the third explains scheduling behavior. It is longer than typical but each clause serves a distinct instructional purpose. The structure is logical and front-loaded with the most important guidance.

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?

Given a mutation tool with no output schema and 4 parameters, the description covers the main operational concerns: the status transitions, the sibling tool divergence, and the scheduling edge case. It could mention return values or success indicators, but that is not essential for an agent to invoke it correctly. Overall it is sufficiently complete for the tool's complexity.

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?

With 0% schema description coverage, the description must compensate. It explains the status enum as a progression of pipeline stages and clarifies the semantics of scheduledFor (planned date, flag behavior). It does not explain lastActor, but that parameter's purpose is somewhat inferable. The key parameters receive meaningful elaboration.

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?

The description opens with a specific verb and resource: 'Move an article through the production pipeline', and enumerates the status values. It clearly distinguishes itself from the sibling mark_article_published by stating that the published transition should use that tool instead, removing any ambiguity about scope.

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?

The description provides explicit when-to-use and when-not-to-use guidance: 'For the published transition use mark_article_published instead' and 'do NOT call mark_article_published before the URL is live'. It also explains the scheduledFor usage for future scheduling, giving the agent clear decision criteria.

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