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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuine context by stating id and history are preserved, i.e. this is a non-destructive state transition. It does not mention that an api_key credential is required or what happens to the prior heartbeat configuration.

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?

A single dense sentence that front-loads the action and states the key preservation guarantee. No filler, though the term 'graduate' costs a little clarity for the brevity it buys.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. Still, for a four-parameter mutating tool with zero schema descriptions, the omission of api_key's role and the polling interval semantics leaves the agent under-informed.

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 0% across four parameters, so the description carries the full burden. It only obliquely gestures at agent_id ('preserving id') and endpoint_url ('endpoint probing'); api_key and check_interval_sec are entirely unexplained, including the 60s default's meaning.

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 clear transition: an existing owned heartbeat registration is converted into public endpoint probing, with id and history preserved. It distinguishes itself from siblings like register_agent_health and send_heartbeat by implying it upgrades an existing registration rather than creating one or sending a ping. The jargon 'graduate' is slightly opaque but the resource and effect are recoverable.

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?

Usage is implied by the precondition 'owned heartbeat registration' — the agent must already have one, so register_agent_health is the prerequisite path. However, there is no explicit when-to-use versus alternatives such as agent_endpoint_assessment or probe_me_now, and no when-not-to-use guidance.

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