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

The annotations already declare this is destructive, open-world, and idempotent, but the description adds important context: the page is publicly visible, publishing adds to the strategy directory without rerunning the strategy, replacing a different result at an existing slug requires expectedKey, and setAsHome changes the home page only when explicitly requested. It omits auth requirements, rate limits, and return behavior, but adds substantial behavioral detail beyond the annotations.

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 front-loads PUBLIC visibility, then states the action, prerequisites, safety constraints, replacement semantics, and optional home-page side effect in compact sentences. Every sentence contributes an operational rule, with no filler.

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 public publishing mutation with nested parameters and no output schema, the description covers visibility, source report, no rerun, replacement guard, and home-page side effect. It still lacks return/confirmation format and auth or permission context, so it is strong but not fully complete.

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 67% schema description coverage, the description compensates by explaining that reportId must come from report, id is a public slug, expectedKey is required only when replacing a different saved result at an existing slug, and setAsHome should be set only when explicitly requested. It does not explain the nested page or presentation fields in detail, but it adds useful meaning for the key parameters.

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 states a specific action and target: publish a completed report to the public website, with PUBLIC visibility, and add it to the strategy directory. It also distinguishes the operation from sibling report by requiring the reportId returned by report and explicitly saying it does not rerun the strategy.

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?

It gives clear usage conditions: call after the user asks to save it, use the reportId returned by report, provide a public slug and client-authored page/presentation choices, never invent result numbers, use expectedKey when replacing a different result at an existing slug, and only set setAsHome when explicitly requested. It does not explicitly compare against alternatives such as share_report or state when not to use this tool, so it falls short of full when/when-not/alternatives guidance.

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