Paw Pulse

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

Annotations only cover the safety profile (non-read-only, non-idempotent, non-destructive). The description adds a genuinely important behavioral trait beyond them: the ingest_token and manage_token are returned exactly once and are unrecoverable, which directly affects how an agent must handle the result.

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 tight sentences with zero filler; the creation action comes first and the token warning is front-loaded as the critical takeaway.

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 no output schema, the description carries the return-value burden and does so by naming the two tokens and their one-time nature. It omits what else is returned (e.g., monitor id) but covers the operationally critical part.

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 every parameter (name, public, webhook_url, grace_seconds, slow_tps_threshold) is already documented in the schema. The description adds no parameter detail, so the baseline 3 applies.

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+resource ("Create a new anonymous Paw Pulse monitor"), which distinguishes it cleanly from delete_monitor and update_monitor. It does not explicitly name siblings, but the create action is unambiguous.

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?

The description gives no when-to-use guidance, no prerequisites, and no alternatives. It never says, for example, that setup_instructions should be read afterward or that existing monitors should be updated rather than recreated.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful extra context beyond that: deletion is permanent, and it cascades to all heartbeats, which the annotations do not 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, zero filler, with the irreversible nature stated up front so an agent sees the risk before anything else.

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 destructive tool whose annotations already flag destructiveness and idempotency, the description adds the two facts that matter most: permanence and cascade to heartbeats. Nothing critical is missing, though the manage_token authorization requirement is only implicit via the schema.

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?

Both parameters are fully documented in the schema (100% coverage), so the schema carries the load. The description adds no format or authorization detail for id or manage_token, so baseline 3 applies.

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 ('Permanently delete a monitor') plus the cascade scope ('and all its heartbeats'), which immediately separates it from the read/update siblings in the toolset.

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?

'Cannot be undone' implies caution and hints this is irreversible, steering toward update_monitor for non-destructive edits, but the description never explicitly says when to use this versus update_monitor or get_status.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the conditional auth rule for private monitors, which is genuinely useful, but omits anything about freshness, caching, or error behavior on unknown ids.

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 with zero filler; the core action is front-loaded before the auth caveat. Every sentence earns its place.

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 read-only tool with fully documented parameters and no output schema, the description covers purpose and the one auth wrinkle. It could say more about what 'status' includes, but nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: manage_token is only needed for private monitors. The id parameter is left to the schema, which already explains its origin.

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 ('Get the current status of a monitor'), making it clearly the read-status tool among create/delete/update/list_heartbeats siblings. It does not explicitly name an alternative, but the distinction is obvious from the verbs of the siblings.

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?

Implied usage is clear (call after create_monitor to poll status), and it adds one conditional: private monitors require manage_token. It gives no explicit when-not or alternative routing, so it sits at the minimum-viable level.

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

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

Annotations already declare this as a safe read (readOnlyHint=true, openWorldHint=false), so the bar is lower. The description adds genuine context beyond the annotations: results are ordered newest-first and private monitors need the manage_token for authorization.

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 compact sentences with the core purpose front-loaded and the auth caveat second. Every clause carries information; no filler.

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 read tool with no output schema and fully documented parameters, the description covers purpose, ordering, and the one non-obvious prerequisite. It omits anything about result volume or paging beyond the limit default, but nothing essential 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 coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks by explaining *when* manage_token is required (private monitors), rather than just that it is the token returned once by create_monitor.

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 (List) and resource (heartbeats for a monitor) with ordering scope (newest first). No sibling tool overlaps with heartbeat listing, but the description never names an alternative or explicitly distinguishes itself from the monitor CRUD siblings.

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 one clear conditional prerequisite: private monitors require manage_token. However, it offers no alternatives to choose from and no when-not guidance, leaving usage only implied for the general case.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds the key behavioral fact that the output is executable shell commands for the target box plus a cron entry. It also flags that the token came from create_monitor, a one-time reveal. It does not say whether repeated calls regenerate identical output or whether the token is consumed.

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: the deliverable first, the required inputs second. No filler, no repetition of the title.

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 no output schema and full schema coverage, the description supplies what's missing: that the return value is shell/cron commands and which inputs feed it. Slightly incomplete on whether the emitted commands are environment-specific or how llm_kind alters them.

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 the schema already documents id, ingest_token, and the llm_kind default/enum. The description only restates the provenance of id and ingest_token and adds nothing about llm_kind, so baseline 3 applies.

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 concrete deliverable: shell commands to install the heartbeat script on the monitored box and schedule it via cron. This is unmistakably distinct from sibling tools like create_monitor or get_status, which manage monitors rather than emit setup steps.

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?

Clear context for invocation: 'Pass the id and ingest_token from create_monitor,' which establishes that create_monitor must run first and supplies both required values. No explicit when-not or alternative tool is named, but the sequencing is unambiguous.

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

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

Annotations already declare it is a non-readOnly, idempotent, non-destructive mutation. The description adds real value beyond that with the patch/merge contract ('Only the fields you pass change'), telling the agent unlisted fields are preserved. It still omits auth/permission requirements and what the response contains.

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, zero filler, with the field list front-loaded and the partial-update rule immediately after it. Nothing to trim.

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 7-parameter mutation with no output schema and annotations covering safety, the description plus schema covers nearly everything an agent needs. The main residual gap is that the required manage_token credential and any failure behavior are left entirely to the schema.

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 86%, so the schema already documents id, manage_token, webhook_url, grace_seconds and slow_tps_threshold. The description's field list roughly mirrors the schema parameters without adding formats, ranges, or clearing semantics beyond what the schema states.

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 verb ('Change') plus the resource ('a monitor's ...') and enumerates the mutable fields (name, grace period, slow threshold, webhook, visibility). The verb alone separates it from create_monitor/delete_monitor, though the description never names those siblings explicitly, which keeps it short of a 5.

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?

The description says what can be changed but gives no when-to-use guidance, no prerequisites (e.g. that the manage_token is required and returned only once by create_monitor), and no mention of alternatives. 'Only the fields you pass change' is a behavioral note, not routing guidance.

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