nucleo-doc-publish

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the safety burden is largely covered. The description adds a genuine behavioral fact — the call can be blocked by quality issues unless acknowledged — but says nothing about what publishing does downstream (visibility, versioning, side effects) or what a blocked response looks like.

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?

Two short sentences with the main action front-loaded and the blocking condition immediately after. The second sentence is grammatically clipped ("require acknowledge") rather than polished, but nothing is wasted.

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 non-idempotent mutation with no output schema, the definition covers the trigger and one gating condition but omits permissions, whether publish is reversible, how acknowledged issues are surfaced, and what the caller gets back. Adequate to attempt the call, thin for calling it correctly on the first try.

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%: acknowledge carries its own description, while postId is only typed as an integer with minimum 1 and no prose. The description implies postId identifies the "current document" and that acknowledge is the escape hatch for blocking issues, which is modest added meaning over a baseline 3 for the coverage level.

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?

"Publishes the current document" gives a specific verb and resource, distinguishing it from siblings like nucleo-doc-patch, nucleo-doc-preview and nucleo-doc-validate. It stops short of naming those siblings or clarifying what publishing changes about the document's state.

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 clause "Blocking quality issues require acknowledge" implies a pre-publish validation workflow and tells the agent a condition under which the call needs extra input. It never names validate/preview as the way to discover those issues, nor states when not to publish (e.g. draft-only docs).

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