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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=false. The description adds meaningful behavior beyond that: it discloses that posting will turn the status page on if it is off, and that apps reading app-config.json will display it. It does not mention permissions or what the non-idempotent behavior means for repeat posts.

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 with the core purpose front-loaded and no filler. The final sentence about app-config.json adds visibility context but is slightly cryptic and less essential than the first two.

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?

With four params at full schema coverage and existing annotations, the safety profile is covered. However, for a mutation tool with no output schema, the description does not say what is returned after posting, nor how it relates to the sibling resolve_status_incident, leaving some gaps an agent would benefit from.

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 description coverage is 100%, so site, level, title and message are already well documented, including the enum values for level. The description adds no parameter-level detail such as formatting for title/message or the relationship between level and display, so the schema does the heavy lifting.

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 ('Post an incident on your site's status page') with examples of incident types. It is clearly distinct from most siblings, but does not mention the closely related resolve_status_incident, so an agent must infer the posting-vs-resolving distinction from the name alone.

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 clear usage context with examples ('e.g. an outage or planned maintenance') and notes the side effect of enabling the status page if it is off. It does not say when NOT to use this tool or route the agent to resolve_status_incident for closing incidents.

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