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

Annotations already declare destructiveHint=true and openWorldHint=true, but the description adds what those hints don't: it mutates the schema registry, affects what clients see, and returns a result code plus published-schema hash. That impact framing and the check-first precondition go meaningfully beyond the structured metadata.

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 with purpose, then sibling routing, then impact, then parameters – a sensible order with no filler. The return-value sentence partially duplicates the output schema, which keeps it from being maximally tight.

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 5-parameter write, the description covers purpose, alternative, side effects, prerequisite, and all parameter roles. Return values are already covered by the output schema, so nothing an agent needs is missing.

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 0%, so the description must carry the load; it names all five parameters (graphId, variant, schema as SDL, optional branch/commit to label the publication) and clarifies format for schemaDocument. It doesn't specify graph ID format or variant constraints, leaving a minor gap.

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 and resource ("Publish a schema to a graph variant") and anchors it to a known operation (`rover graph publish`). It explicitly distinguishes itself from the sibling PublishSubgraph by naming the monograph-vs-subgraph split.

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?

Gives explicit routing: "Use this for a monograph; use PublishSubgraph for one subgraph of a federated graph." It also states a prerequisite workflow ("Run RunSchemaCheck first to see the effect on client operations"), covering when-to-use and what to do before calling.

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