hub_heartbeat

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

Without any annotations, the description carries the full burden and does so excellently. It discloses the destructive overwrite behavior, the freshness semantics (judged at read time from ttlMin, default 15min, same pattern as hub_claim), the 5-minute throttle on the node snapshot refresh, and the node-local directory that never syncs. This is exactly the kind of hidden behavior that an agent needs to make correct consequences.

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 sentences each carry active operational content: purpose and when, overwrite/timeout semantics, and a rarely surfaced cross-node refresh constraint. The core instruction is first in the lineup, and each sentence earns its place without filler or repetition.

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 tool with six optional parameters and no output schema, the description provides all the practical facts required for a safe call: when to invoke it, what record is overwritten, how freshness is judged, and why a cross-node snapshot is needed. It also accounts for the asymmetric cross-node visibility issue, which is the most non-obvious piece of context.

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 schema covers 100% of the parameters with detailed descriptions, so the description does not need to repeat them. It adds only minimal extra parameter-level meaning—ttlMin's freshness role and role's link to hub_brief—and even that mostly reiterates what is already in the schema. The description primarily enriches behavioral context rather than parameter definitions.

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 first phrase, 'Record that an agent is alive,' uses a specific verb and resource, then sharpens the intent by placing it in an explicit call sequence: 'call it each work cycle (right after hub_report, before the next hub_queue_wait) so... show up in hub_presence.' This clearly separates the heartbeat tool from its more than 30 siblings, including hub_report, hub_presence, and hub_claim.

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 explicit context and a precise time to call the method: 'each work cycle (right after hub_report, before the next hub_queue_wait)' and explains the rationale for MCP/headless agents. It does not mention an explicit when-not-to-use case or list a competing alternative tool, so it falls short of a fully elaborated exclusion clause.

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