Paw Pulse

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

Annotations already declare non-readOnly, non-destructive, non-idempotent, so the safety profile is covered. The description adds genuinely non-obvious behavior: the response contains ingest_token and manage_token returned exactly once and unrecoverable, which tells the agent this is a one-shot provisioning step with irreversible loss on failure. It omits whether creation requires auth despite the 'anonymous' label and whether repeated calls create duplicates, which non-idempotent implies but doesn't confirm.

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 sentences, no filler. The critical, easy-to-miss fact (tokens are returned once and cannot be recovered) is placed in the second sentence where it reads as an imperative warning rather than being buried.

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 correctly compensates by naming the two fields returned. For a zero-required-parameter creation tool this is nearly complete; the remaining gaps are whether the call is authenticated, what defaults apply when all parameters are omitted, and whether a failed attempt still consumes the one-time token issuance.

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%, and every one of the 7 optional parameters carries its own explanation of format and effect, so the schema does the semantic work. The description adds no parameter detail at all beyond the word 'anonymous', 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 and resource ("Create a new ... monitor") and characterizes it as "anonymous" and tied to "Paw Pulse", which meaningfully separates it from update_monitor and delete_monitor in the sibling list. It stops short of naming or contrasting those siblings explicitly, so an agent infers the create-vs-modify distinction rather than being told.

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 verb: call this to provision a new monitor. There is no explicit when-to-use vs update_monitor guidance, no statement about whether an existing monitor could be reused, and no prerequisites or error conditions. The token-storage warning is operational guidance but about what to do after the call, not about when to call it.

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?

The annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety profile is covered. The description adds genuine value with partial-update semantics (unspecified fields are untouched), but says nothing about authentication requirements, whether it errors on unknown/no-op updates, or what is returned. Adequate, not rich.

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, front-loaded with the action and the affected fields, with the partial-update caveat immediately after. Nothing is padded, though the field enumeration could be trimmed or made exhaustive rather than partial.

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 9-parameter mutation tool with no output schema, the description covers the core patch semantics but leaves out the auth credential's role, the null-clears-optional-fields convention, and two updatable fields. Sufficient to call correctly only if the agent reads the schema closely.

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 89%, so the baseline is 3. The description contributes one real piece of meaning the schema lacks — that omitted fields are preserved rather than reset — but it doesn't mention the null-to-clear convention or the manage_token requirement that govern several parameters.

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?

Uses a specific verb ("Change") on a specific resource ("a monitor") and enumerates the mutable fields. It clearly occupies a different role than its siblings (create_monitor, delete_monitor, get_status), but the field list is incomplete — min_gpu_pct and expected_model are silently omitted, so it doesn't fully describe its own surface.

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 obvious from the name and sibling set, but the description never states when to reach for this versus create_monitor or delete_monitor, nor any prerequisite like needing the manage_token. "Only the fields you pass change" is a useful semantic hint but is not an explicit usage rule.

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