get_heartbeat_state

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

With no annotations, the description carries the full burden and does the most important thing: it explicitly guarantees no side effects ("No renewal or delivery is triggered"), which is exactly the safety signal an agent needs. It also flags that next_wake is a compatibility alias, a behavioral quirk of the response rather than the call itself.

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 dense sentences with the primary scope front-loaded and the no-side-effect caveat placed at the end where it is most needed. The middle sentence about the next_wake alias is slightly cryptic in isolation but earns its place as a disambiguation note.

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 zero-parameter read tool with a published output schema, the description supplies the two things the schema cannot: what the state comprises and that reading it mutates nothing. The remaining gap is that terms like "global wake eligibility" and "heartbeat-only hold" are not defined for an agent unfamiliar with the heartbeat subsystem.

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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The one aliasing note about next_wake relates to output shape, which the output schema already covers.

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?

Opens with a specific verb ("Inspect") and enumerates the resources it returns: named schedules, global wake eligibility, heartbeat-only hold, delivery receipt. This is clearly distinct from the mutating siblings schedule_next_wake and cancel_next_wake, though the phrase "heartbeat-only hold" is internal jargon an agent may not decode.

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 rather than stated: "Inspect" plus "No renewal or delivery is triggered" tells the agent this is the safe read path, but neither sibling schedule_next_wake nor cancel_next_wake is named, and no condition for choosing this over them is given.

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