heartbeat_testPut one test alert (event "test") in a heartbeat check's inbox, to check your handling before a job really stops. Never an email; the check is untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| instance_id | Yes | Utility instance id from buy or list_utilities. | |
| heartbeat_id | Yes | heartbeat id (hbc_...) from heartbeat_add or heartbeat_status. | |
| passport_token | No | Your amp_ token, only if you have no app sign-in and cannot send a header. |
Changes observed during successful MCP inspections.
Input schema / examplesAdded value: +[
+ {
+ "heartbeat_id": "hbc_exampleexampleexample2",
+ "instance_id": "hbt_exampleexampleexample2"
+ }
+]Input schema / properties / passport_token / descriptionPrevious value: -"Your amp_ token, only if your app has no sign-in and cannot send it as an Authorization header."New value: +"Your amp_ token, only if you have no app sign-in and cannot send a header."Input schema / $schemaRemoved value: -"https://json-schema.org/draft/2020-12/schema"Input schema / properties / passport_token / descriptionPrevious value: -"Your amp_ token, only if your client cannot send it as an Authorization header; leave it out when your MCP app signed in."New value: +"Your amp_ token, only if your app has no sign-in and cannot send it as an Authorization header."Input schema / properties / passport_token / maxLengthAdded value: +200Input schema / properties / passport_token / patternRemoved value: -"^amp_(?:s_)?[A-Za-z0-9_-]{43}$"Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavior beyond the annotations: no email is sent and the check itself is untouched, so the mutation is confined to the inbox. That reconciles readOnlyHint=false (it does write an alert) with the reassurance that nothing else changes — useful context the annotations alone wouldn't convey.
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 short sentences and a clause; the action and its effect are front-loaded with zero waste.
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 simple, single-effect write with no output schema and fully documented parameters, the description covers what happens (one test event is deposited), what doesn't (no email, check unmodified). Nothing needed to call it correctly is missing.
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%, with instance_id and heartbeat_id documented including where to obtain them, so the schema carries the parameter burden. The description only adds the event type ("test") and nothing about the optional passport_token — baseline 3 is appropriate.
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 — put one test alert (event "test") in a heartbeat check's inbox — with the scope word "test" making it unmistakable against real alert tools. An agent can tell this apart from heartbeat_add/heartbeat_status without opening the schema.
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 context for when to call it: to check your handling before a job really stops. It doesn't name an explicit alternative or state when-not-to-use, but the "test vs real" framing makes the selection condition obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.