hookpulse

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that – no statement of what the index contains, how large it is, or whether it is meant as a bootstrap call.

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?

A single short sentence, front-loaded and free of waste, but its brevity comes from under-specification rather than tight writing. There is room for one more clause explaining contents or intended use at no cost to readability.

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 no parameters, the description is the only place an agent could learn what this call returns, yet it says only 'Full index.' For a zero-arg tool whose entire value is its payload, that is a real gap.

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 schema has nothing to document and the baseline of 4 applies. The description neither helps nor harms here.

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 description largely restates the name and title ('API index' → 'Full index of the HookPulse API') with no verb describing the action. It hints at a discovery/listing role but never says what an agent would get back or what 'index' contains, so it does not distinguish itself from sibling list_* tools.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives among the many siblings (list_endpoints, list_sites, list_events, list_templates). The agent is left to guess whether this is a discovery entry point or a bulk data fetch.

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 readOnly/idempotent/non-destructive, so safety is covered; the description instead adds genuinely useful domain behavior: $0.10 per additional monitor for e-mail alerts, trial post-expiry alert limits to the ten oldest monitors, and the warning that this value is authoritative over documentation. It does not describe response shape or refresh timing, but the behavioral context is well above the annotation baseline.

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?

Front-loaded with what is read, followed by cost and gating rules; no filler sentences. Slightly penalized because the final sentence is long and the phrase 'it is the number IN FORCE, not the documentation's' is cryptic on first read.

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-param, read-only tool with no output schema, the description covers what the call returns, the pricing rules that make the numbers actionable, and the trial-expiry consequence. The only gap is that the concrete response fields are listed loosely rather than as a shape, which matters slightly given there is no output 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?

The tool takes zero parameters, so per the baseline there is nothing the description must compensate for. The description correctly spends no words on argument semantics and instead uses the space on result meaning.

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 description opens with a specific verb ('Read') and enumerates the exact resources returned: free allowances, billing-disabled options, prices, and the account's 7-day trial. It is clearly a billing-state reader, distinct from write-side siblings like buy_plan/cancel_plan, though it never explicitly distinguishes itself from `pricing` or `list_plans`.

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 an explicit trigger: 'Check before creating the second monitor or lowering the interval,' which tells the agent precisely when this tool is the right call. It also names a fallback endpoint (`GET /api/plans`) for monitors that need a plan, though it does not state any when-not-to-use condition.

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?

Goes well beyond the annotations (readOnly=false, idempotent=false) by disclosing the 30-day non-renewing term, the 402 price-negotiation response, accepted payment headers (X-Credito, PAYMENT-SIGNATURE v2, X-PAYMENT v1), wallet-based ownership for unauthenticated buyers, and replay protections (compra mark, single-settle nonce). This is exactly the context needed to invoke a paid mutation correctly and avoid double charges.

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?

The description duplicates content almost verbatim: 'Each purchase lasts 30 days, with no automatic renewal' appears twice, and the 402/payment explanation is repeated with slight rephrasing in consecutive blocks. The redundancy bloats the text and pushes key facts (replay protection, receipt retention) out of a front-loaded position.

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 paid mutation with no output schema, it covers pricing discovery, payment mechanics, ownership resolution, and error recovery — the important gaps are filled. The duplicated wording makes the payment/ownership sequence harder to parse than it needs to be, 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 description coverage is 100% and the single enum parameter is already fully documented in the schema. The description restates the same tier-to-monitor-mapping but adds no new syntax or semantics, 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+resource (buy a plan) and enumerates the three tiers with their monitor counts, which cleanly separates it from siblings like list_plans, pricing, and cancel_plan. An agent knows exactly what this tool accomplishes.

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 lays out the calling flow — call, receive a 402 with the price, pay via prepaid credit or x402, then repeat — which tells the agent how to actually use the tool. It does not name alternatives (e.g., use list_plans to inspect tiers or cancel_plan to reverse), so there is no explicit when-not guidance.

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 description supplies genuinely useful behavior (nothing further is charged, refund path, access kept until keeps_until, monthly card subscription stops, pointer to account.cancel.losses). However, it also states the user must accept losing what the plan added, which conflicts with the declared destructiveHint=false and with the schema's own 'losing what the plan added' wording — an agent trusting the annotation would underestimate risk.

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?

Front-loaded with the key action, but the refund rule is stated twice in near-identical wording ('a purchase under 7 days and a paid period that has not started are refunded and end now' vs the later restatement), and the literal JSON example duplicates the schema. Roughly half the text is redundant.

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?

No output schema exists, and the description compensates by naming the keeps_until field and pointing to account.cancel.losses in GET /api/plans for the losses detail, plus the out-of-band refund route. Only the immediate response shape is unaddressed.

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% and the single parameter already documents that it must be true and what accepting it means. The description only restates this and shows a literal payload example, adding no semantics beyond the schema.

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 opening sentence 'Cancel the active plan' gives a specific verb and resource, which is easily separable from siblings like buy_plan, list_plans, and billing. It does not explicitly name those siblings, but the 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?

It states the precondition (requires accept_data_removal: true), the effect window (refunded if under 7 days or unpaid period), and routes USDC/credit-paid purchases out of the tool toward e-mail refund. Missing an explicit 'use buy_plan instead if...' contrast, but usage context is clear.

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?

Beyond the annotations it discloses a hard rate limit (one call per 10 seconds per destination host, shared across all users) and a meaningful side-effect nuance: the first check produces no alert. That is exactly the kind of context annotations cannot carry, though it does not mention auth requirements or 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?

The rate-limit sentence is duplicated verbatim ('One call every 10 seconds per destination host.' appears twice), wasting a full sentence. The remaining content is well front-loaded and purposeful, but the repetition is a clear editing defect.

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 does enough by explaining that the returned state is the site's first observation and that no alert is emitted. It still omits what fields the response carries, but an agent can call it correctly with what is provided.

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% and both parameters are fully documented in the schema, so the description need not restate them. It adds nothing about `id` or `guest_token` beyond what the schema already says, leaving this at the baseline.

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 sentence names a specific verb and resource ('Check a site monitor now') and the closing sentence clarifies its role relative to the automatic per-minute check. It stops short of naming a sibling tool it should be chosen over, but the immediate-vs-scheduled distinction is clear.

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 tells the agent when to reach for it: to obtain the first state of a newly created site, and implicitly not to poll repeatedly afterwards since the per-minute check supplies state and alerts. It gives no explicit 'do not use when' clause, but the context is strong enough to guide selection.

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?

Beyond the annotations, it discloses important behavioral traits: no captcha/account/payment, rate limiting of one message every 10 seconds per network with queuing rather than error, email delivery with `email` as reply address, and multipart voice submission details with file size limits.

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?

The description is front-loaded with useful context, but it repeats the same facts about captcha/payment and the 10-second rate limit twice, making it less concise than it could be.

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 an 18-parameter tool with an output schema absent but full schema description coverage, the description covers operational constraints, delivery behavior, and multipart voice submission well. It does not describe the response format or confirmation behavior, which is a minor remaining gap.

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 useful meaning for key parameters: `tipo` routes proposal types, `espaco` uses placement ids from `GET /api/partners`, and voice submissions use `dados` plus `audio` with explicit size and format constraints.

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 description states a specific verb and resource: writing to the people behind the product for a question or a sponsorship/partnership/advertising proposal. It is clear about the tool's purpose, though it does not explicitly contrast with any sibling tool.

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 names concrete use cases (question, sponsorship, partnership, advertising proposal) and explains the conditional route via `tipo` with placements from `GET /api/partners`. It lacks explicit when-not-to-use guidance or named alternatives.

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 establish that this is a non-idempotent, non-destructive write, and the description adds real behavioral context beyond them: the guest_token returned without an owner token and the need to keep it private, the HTTP 402 on charged requests, and that alert timing depends on the check cycle. Several sentences ('Your agent can stop after setting up the monitor', 'A check-in proves the signal arrived, not that a backup can be restored') are vague enough that their operational meaning is unclear.

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?

The core action is front-loaded and the key operational facts (mode selection, guest_token, 402) come early. However, the paragraph runs to nine sentences and several trailing lines read as defensive hedging rather than actionable guidance, diluting the signal.

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 12-parameter mutation tool with no output schema, the description covers auth, billing and alerting well, but omits what the response actually contains and how the created monitor is signalled afterward (the ping slug/URL used by signal_slug, ping_slug, ping_ingest). That is a meaningful gap for an agent trying to complete setup end to end.

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 combinatorial meaning the schema cannot express: which parameters form the cron-schedule mode versus the interval mode, and that max_duration_sec detects an open run exceeding its limit. It does not explain interaction rules for paused_until or alert_repeat_sec, but the mode-selection guidance lifts it above baseline.

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 opening sentence names a specific verb and resource ('Create a monitor for a routine') and the rest clarifies the two monitoring modes. It is clear what the tool does, though it never explicitly distinguishes itself from siblings like create_site or import_crontab, which also create monitoring resources.

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 concrete selection guidance between modes ('cron, tz and grace_sec for a schedule, or interval_sec for a fixed check-in interval') and directs the agent to read billing before choosing a paid option. It stops short of saying when to use this tool instead of create_site or import_crontab.

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 is a non-read-only, non-idempotent, non-destructive write. The description adds genuinely new behavioral context beyond that: the token is the only way back to the monitors unless they are tied to an e-mail, i.e. losing it is effectively irreversible. Auth requirements and repeat-invocation behavior are still unstated.

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 then the critical caveat. The token prefix and 'monitors' are slightly cryptic, but no sentence is wasted.

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 tool whose annotations cover the safety profile and which has no output schema, the description covers purpose and the one high-stakes consequence of losing the token. It leaves the nature of a 'guest' and the 'monitors' undefined, but nothing needed 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?

The tool takes zero parameters, so there are no parameter semantics for the description to carry; the baseline for a parameterless tool is 4. Nothing in the description misleads about inputs.

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 description names a specific verb and resource (creates a guest token) and even shows the token prefix ('hp_…'), so the agent knows exactly what is produced. It does not, however, distinguish this from sibling token/key tools such as ingest_key or ingest_key_rotate.

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?

There is no statement of when to create a guest versus using another tool, no prerequisites, and no mention of the related siblings. The only guidance given is a post-hoc warning to keep the token, which is retention advice rather than usage routing.

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 a non-read-only, open-world, non-idempotent, non-destructive create operation. The description adds substantial behavioral context beyond that: polling every interval_sec (default 300), down/recovery alerts, guest_token secrecy, billing/402 handling, schedule ownership, missed-run detection, and alert timing tied to the check cycle. Some sentences are tangential, but the behavioral disclosure is strong.

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?

The first sentence front-loads the core monitoring behavior, but the description then strings together several operational notes without tight grouping. The sentence about a check-in proving the signal arrived rather than a backup being restorable is tangential to create_site, and a few other notes could be consolidated or removed.

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 moderately complex create tool with a nested check object, no output schema, and rich schema coverage, the description covers setup behavior, guest_token output, billing, and alert scheduling. However, it omits the normal success return shape, such as a site identifier or monitor details, and does not explicitly guide the agent toward or away from sibling tools.

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 all 8 parameters, including the nested check object fields, are already documented in the schema. The description reinforces interval_sec default 300 and guest_token ownership but does not add meaningful semantics for name, tags, alert_to, alert_url, or paused_until beyond what the schema already provides, making the baseline 3 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?

The opening sentence identifies the resource and action clearly: it sets up a website monitor that calls check.url at an interval and alerts on downtime and recovery. It is understandable as a creation/setup tool, though it does not explicitly name or distinguish itself from siblings such as check_site or list_sites.

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 supplies some usage prerequisites, including reading billing before a paid option, the 402 charged-request behavior, and guest_token handling when no owner token is supplied. It also hints that a single paid probe is not continuous monitoring, but it never explicitly names check_site or states when not to use create_site, so the boundary with alternatives is left to inference.

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, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the 'owner's' scoping qualifier and says nothing about what else is lost (events, monitors, history), whether the operation is reversible, or that an owner token is required. With annotations doing most of the work, this is thin but not misleading.

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?

A single short sentence with zero wasted wording and the action front-loaded. It is efficient, though the terseness edges into under-specification rather than crispness.

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, owner-scoped operation with no output schema, the description omits the consequences an agent needs before calling it: whether associated events or monitoring data are removed, whether the action is permanent or a soft deactivate (the schema hints 'deactivate'), and what the caller gets back.

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 both parameters are already documented, including the X-Guest-Token usage for guest_token. The description adds no meaning beyond that, which is the baseline expectation when the schema is fully described.

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 ('Removes ... endpoint'), which is enough to distinguish it from create_endpoint, get_endpoint, and list_endpoints in the sibling set. It loses a point because the schema calls the object a 'monitor' while the description says 'endpoint', leaving the agent to reconcile the two terms itself.

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?

There is no guidance on when to use this tool versus alternatives, nor any precondition or caution. Nothing tells the agent that deactivation rather than true deletion may be involved, or what state the resource must be in first.

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?

Goes well beyond the annotations by disclosing the payment protocol (unpaid request returns 402 with the price, payment recorded in `cobranca`), that failed/down targets are still charged, and that a probe-network failure returns 503 with no charge. This is exactly the cost-and-side-effect context an agent needs before spending money, and it is consistent with readOnlyHint=false and destructiveHint=false.

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?

Front-loads the purpose and the return data in the first sentence, then layers payment semantics. Some phrasing is awkward and redundant ('A site that is down is the answer ... and is charged: the call was made'), but nothing is wasted given the volume of behavioral information conveyed.

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 burden of explaining return values, and it does: the fields checked, `ok: false` with `reason` for down sites, 402 with price for unpaid requests, and 503 for probe failure. Nothing an agent needs before invoking a paid, non-idempotent call 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%, so every parameter (url, method, keyword, timeout_ms, expect_status) is already documented in the schema, including the note that keyword forces GET. The description adds no parameter-level detail beyond that, so the baseline of 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 verb and resource plus the exact scope: one check of one URL, returning status, response time, keyword result and TLS certificate. The phrase 'with no account and no monitor' and 'the probe of the site monitors' implicitly distinguishes it from the sibling check_site, which is a monitor-based tool.

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 makes clear this is a one-off, pay-per-call check rather than a recurring monitor, which points an agent toward check_site for ongoing monitoring. It doesn't explicitly name that alternative or state exclusions, so it stops short of full when/when-not guidance.

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?

Beyond the readOnlyHint, idempotentHint, and destructiveHint=false annotations, the description explains the monitor-token trust model: it can read state for a third-party dashboard without exposing the owner credential. It also discloses that duration metrics are computed at read time over a retained event window, which is useful behavioral context not covered by annotations.

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?

The purpose is front-loaded in the first clause, but the remaining prose is dense, with nested parentheticals and phrases like "the list does not pay for it" that require interpretation. Most content is relevant, though the structure could be clearer and more scannable.

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 responsibility for describing return values; it usefully explains next_expected_at, p50_ms, and max_ms. However, it does not describe the rest of the endpoint status payload or error behavior, so it is only partially complete for an agent invoking the tool.

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 defines id, token, and guest_token, setting a baseline of 3. The description adds partial token-choice meaning with "use the endpoint token if you have it" and the read-only monitor token, but it does not explain guest_token usage or further clarify id semantics.

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, "Status of one endpoint," states a specific resource and scope, making clear this is a single-endpoint read rather than a list operation. It does not explicitly name sibling alternatives, so it stops short of full sibling differentiation.

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 "use the endpoint token if you have it," but that is authentication guidance for a parameter rather than guidance on when to choose get_endpoint over list_endpoints or other tools. It provides no explicit when-not or alternative-tool routing.

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 readOnly, idempotent, closed-world and non-destructive, so the safety profile is fully covered elsewhere. The description adds useful scope context by saying it reports service liveness rather than monitor status, but says nothing about auth requirements, latency, or what the health response actually signals (degraded vs. down).

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, and the primary action is front-loaded before the clarifying exclusion. Nothing in it could be cut without losing signal.

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 parameterless liveness probe with full annotation coverage, this is close to sufficient; the main action and the key non-goal are both stated. The one gap is that with no output schema, the phrase "the health response" leaves the shape of the return value undefined.

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 no parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The absence of required input is implicitly confirmed by the description describing a pure read.

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?

Description gives a specific verb and resource ("Read service liveness") and explicitly rules out one misreading with "does not check a monitor", which separates it from check_site. It stops short of naming any sibling by name, so the differentiation is generic rather than routed.

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?

"before using HookPulse" gives a clear temporal trigger for when to call it, which is more than most zero-param tools offer. There is no statement of when not to call it, no failure-handling advice if liveness is down, and no named alternative such as check_site or status_feed_url.

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 only declare the coarse profile (not read-only, not destructive, not idempotent); the description goes well beyond by disclosing the dry-run default, all-or-nothing write semantics, credential redaction before the command becomes a visible monitor name, an explicit return field list, and the 400/401/402 error and payment flows. Nothing here contradicts the annotations — writes only occur under apply=1, matching readOnlyHint=false.

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?

The front-loaded dry-run warning is well placed, but the key point is stated twice almost verbatim ('Without apply=1 nothing is written' and 'Without `?apply=1` **nothing is written**'), and the ignored/why explanation is also repeated. The curl example and error catalogue are useful, but the duplication costs it.

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 three-parameter mutating import tool with no output schema and no annotations covering side effects, the description supplies the return shape field-by-field, redaction behavior, ignored-input rules, auth, payment terms, and a runnable example. An agent can call it correctly, including the auth and 402 retry path, without further 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: apply=1 is all-or-nothing rather than per-line, omitting it yields a non-mutating proposal, and the crontab body is text/plain content rather than a path. guest_token semantics are left to the schema, which is acceptable given full coverage.

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 opening sentence gives a specific verb and resource ('Reads a crontab and proposes one monitor per scheduled line'), and the apply=1 path is clearly distinguished from the proposal path. This differentiates it from single-resource siblings like create_endpoint, since the unit of work is an entire crontab.

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 states explicitly when nothing is written (no apply=1), when writing occurs (apply=1, all-or-nothing, same rules as POST /api/endpoints), and what input is ignored (comments, variables, @reboot). An agent knows the default safe behavior and the opt-in condition without inference.

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?

Adds substantial behavior beyond the annotations: one key per owner, first-call minting, monitors created lazily on first check-in inside the free tier, a 402 response beyond the free tier that creates nothing, and key persistence across sign-in. There is mild tension with readOnlyHint=true since a key is minted on first call, but the mint is idempotent and owner-scoped, so it is not a flat contradiction. It does not state whether the returned key is a secret to be stored securely.

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?

The key behavior is front-loaded, which is good, but the text is padded: the '/in/<key>/<slug>' URL appears twice, and 'inside the free tier' is emphasized twice (once bolded). A single tightened sentence plus the 402 caveat would say the same thing.

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 one-parameter key-provisioning tool with annotations already declaring safety and idempotency, the description covers the important surprises: lazy minting, free-tier limit with 402, and persistence. The remaining gap is guidance on rotation/reissue (ingest_key_rotate) and how to treat the returned secret.

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 single parameter guest_token is fully documented in the schema (100% coverage), including the X-Guest-Token header and reuse semantics, so the schema carries the load. The description adds nothing about the parameter — notably it never says the key is owner-scoped via guest_token or what happens when it is omitted (0 required 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?

The description states a concrete verb and resource: it 'Returns (minting the first time) the key for /in/<key>/<slug>'. An agent immediately knows this yields an ingest key scoped to an owner. It does not name the near-sibling ingest_key_rotate, so differentiation is left implicit, keeping it out of 5 territory.

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 conveyed indirectly: 'Instruments a whole fleet with no setup call per job' and 'Point a whole fleet at /in/<key>/<slug>' tell the agent the intended scenario. However, it never says when to prefer ingest_key_rotate, when a key already exists, or what to do if the caller already holds one — no explicit alternatives or exclusions.

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 known; the description adds real value by defining the blast radius — existing monitors survive and only the power to create new ones is revoked. The gap is that it never says whether the new key is returned in the response, which is the single most operationally important fact for a rotate call with no output schema.

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?

The core fact is front-loaded, but the same point is restated three times ('the previous one stops creating monitors', 'existing ones keep working', 'rotating only revokes the power to create new ones'). It is short in absolute terms yet meaningfully redundant.

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 mutation with no output schema, an agent needs to know how the replacement key is obtained and whether the caller must hold the owner token; neither is covered. The blast-radius explanation is complete, but the post-call workflow is not.

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?

One parameter with 100% schema description coverage, so the schema already explains guest_token and its X-Guest-Token usage. The description adds nothing about the parameter, which is acceptable at this coverage level but is the baseline, not above it.

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 ('Rotates the ingest key'), which cleanly separates it from the sibling ingest_key (view/read) and ping_ingest (test). It never names those siblings explicitly, so differentiation relies on the reader inferring it from the verb.

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 only implied: the note that the old key stops creating monitors suggests this is for key-compromise or key-rollover situations, but there is no explicit 'use when' statement, no prerequisites, and no pointer to ingest_key if the agent just wants to view the current key.

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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile needs no restating. The description adds only the owner scoping (endpoints belong to the token's guest/session); it says nothing about ordering, pagination, or whether empty results are possible. Given the annotation coverage, a 3 is appropriate but the added context is thin.

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?

A single short sentence with no filler and the resource stated up front. It is efficient, though its terseness borders on under-specification rather than optimal concision.

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?

The tool is simple: one required token parameter, no output schema, and annotations that fully cover the read-only behavior. The description says enough to call it but omits anything about the shape or volume of results, which is the main remaining gap for a list operation.

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?

With one parameter at 100% schema description coverage, the schema already explains that guest_token is the private owner token sent via X-Guest-Token. The description only restates the ownership relationship ("guest's/session's") and adds no syntax, format, or sourcing detail beyond the schema.

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 description has a specific verb and resource ("Lists ... endpoints") and scopes it to the guest/session owner, so the basic operation is clear. However, it does not distinguish this from siblings such as get_endpoint (single endpoint retrieval) or list_sites/list_events, and "guest's/session's" leaves the owner-scoping rule only implied rather than stated.

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?

There is no guidance on when to use this versus get_endpoint or the other list_* tools, and no mention of prerequisites beyond the token being required. The agent must infer that this is the bulk-retrieval counterpart to the singular getter.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description's only added behavioral signal is "latest," which implies a bounded, recency-ordered result rather than full history — useful, but very thin given no output schema exists.

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?

It is short, but brevity here is under-specification rather than conciseness: a four-word noun phrase is not a sentence and carries no front-loaded operative clause. There is nothing to trim, but nothing informative is present either.

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 taking a required monitor id, an optional token, and a guest owner token, and returning unspecified events, the description explains almost nothing. With no output schema, the description should at minimum describe what counts as an event and whether results are limited or paginated.

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 all three parameters (id, token, guest_token) are documented in the schema itself. The description adds no meaning about how id or guest_token affect the scope of returned events, so this sits at the baseline 3.

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?

"Latest ingest pings." is a four-word fragment with no verb; it only clarifies that the "events" in the tool name correspond to ingest pings. It does not say whether the tool returns a list, a single record, or what window it covers, and it offers no distinction from siblings such as ping_ingest, list_endpoints, or status_feed_url.

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?

There is no when-to-use guidance, no exclusion of alternatives, and no statement of prerequisites (e.g., that a monitor id or guest token is needed to see private pings). The word "latest" hints at recency but provides no implied workflow guidance.

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 establish readOnly, idempotent, non-destructive and closed-world behavior, so the bar is lower. The description adds genuinely useful semantics beyond them: purchases last 30 days with no auto-renewal, and the account field is null when unauthenticated, which tells the agent how to interpret a partial response.

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?

The sentence 'Each purchase lasts 30 days, with no automatic renewal.' is duplicated verbatim, which is wasted space in an otherwise two-sentence description. The substantive content is front-loaded and tight apart from that 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?

With no output schema and no parameters, the description carries the return-value burden and does so: it enumerates price, term, and active plan, and explains the null-account case. Ordering, currency, and the shape of the plan objects are left unspecified, but the essentials for correct invocation are present.

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 no schema surface for the description to compensate for. The description correctly adds no parameter commentary.

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 description names the resource and its contents precisely: plans for sale with price and term, plus the account's active plan. That distinguishes it from the mutation siblings buy_plan and cancel_plan, though the implicit overlap with the 'pricing' sibling is not addressed.

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?

There is no statement of when to call this versus alternatives such as pricing or buy_plan, and no mention of what precedes a purchase. The only contextual hint is that a null account is returned without credentials, which is incidental rather than usage guidance.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description earns credit for behavior annotations cannot express: the result doubles as the snapshot baseline for the /api/realtime/ subscription, after which updates arrive as events. It omits any statement about ordering, volume, or pagination for large site lists.

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, front-loaded with the returned state before the realtime relationship. The trailing clause about screens never polling is slightly promotional but still carries the practical implication of the snapshot semantics.

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 single-parameter, read-only list tool with full annotation coverage and no output schema, the description covers what is returned (states plus last check) and how it fits the realtime flow. Only scale/ordering details are absent, a minor gap at this complexity.

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% and the single guest_token parameter is documented in the schema itself (X-Guest-Token header, owner scoping, reuse). The description adds no parameter meaning beyond that, so the baseline of 3 for a well-covered schema 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?

The description names the resource ('every site you monitor') and specifies exactly what is returned ('the state ... up, down, waiting, paused, with the last check'), which is more precise than the name alone. It stops short of an explicit verb and does not distinguish itself from look-alike siblings such as check_site or list_events.

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: the realtime note ('after it, every check arrives as an event, so a screen never has to poll') suggests taking this snapshot first and then consuming events. There is no explicit when-to-use or when-not-to-use guidance versus check_site or list_events, so the agent must infer the choice.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description does add one genuinely useful behavioral fact — that `miss_json` and `recovery_json` here are byte-identical to the bodies POSTed to your `alert_url` — which is context an agent cannot get from the annotations.

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?

It is short (three sentences) and wastes no padding, but it is poorly front-loaded: the leading sentence about ingesting snippets is the least informative part and delays the one fact that matters. The clauses are dense and the referent of 'It' in the second sentence is ambiguous.

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 zero parameters, no output schema, and safe-read annotations, the burden is light, and the description does reveal the payload keys an agent will receive. However, it never confirms the return shape is a list of templates or how many templates exist, so an agent still cannot predict the response with confidence.

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 there is nothing for the description to disambiguate; baseline 4 applies. Mentioning the two template keys (`miss_json`, `recovery_json`) is a bonus that hints at what the empty-argument call yields.

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 description never states plainly what the tool does or that it returns a list of templates; it opens with 'Ingest snippets and the JSON HookPulse POSTs on a miss,' which describes side effects or rationale rather than the tool's action. Its head-noun is the reason the tool exists ('so nobody guesses the alert format'), not the verb+resource the agent needs to distinguish it from siblings like list_endpoints or list_events.

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?

There is no when-to-use statement, no alternative tool named, and no trigger condition. The mention that Slack and Discord receive only the field they read is integration trivia, not guidance about when an agent should call list_templates versus any other listing tool.

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, idempotentHint and destructiveHint=false, so the safety bar is lower; the description still adds genuinely useful context: unauthenticated by design (the ID is the secret) and no per-ping quota or cost. What it omits is the observable effect of a ping and any rate-limit or 404-on-unknown-ID behavior.

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 short, front-loaded sentences with the mechanic stated first and the two operational caveats after; nothing is padded. Minor cost is that the telegraphic phrasing ('GET on /in/:id', 'the caller is a cron') assumes protocol familiarity.

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?

No output schema exists, so the description carries the burden of explaining the result of a ping and it does not: no mention of the response, of what state changes on the monitor, or of error cases for an unknown ID. It is adequate for authentication and cost expectations but incomplete for outcome expectations.

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% and the schema already explains that id comes from Monitor.ingest_url. The description adds a real semantic layer beyond the schema: that the ID functions as the credential, which changes how an agent should treat and store it.

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 description gives a concrete mechanic ('Simulates the cron: GET on /in/:id'), which tells an agent roughly what the tool does. But it never states the effect of the ping (does it record an event, trip a monitor, emit a signal?) and never differentiates itself from the sibling ping_slug, which is a near-identical name.

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 'simulates the cron' and the note that no credential is needed, so an agent can infer this is a test/manual-trigger path. There is no explicit when-to-use versus when-not, and no pointer to ping_slug, signal_* or list_events as alternatives.

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 description explicitly states that this tool writes state: it creates a monitor, and 'a rejected creation writes no monitor or event' implies successful creation does write. The annotations declare readOnlyHint=true, so the structured metadata mislabels a state-creating call, which is exactly the contradiction case. The description's own disclosure is detailed (idempotency, free-tier gating, 402 with accepts[], normalization), but the conflict with the annotation is disqualifying for this dimension.

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?

Front-loaded with the core action and identity rule, then limits, transport, and errors in a workable order; the example and error table both earn their place. There is redundancy — 'The same slug uses the same monitor' is restated as 'the same slug always means the same monitor, so a retry never creates a second one' — and the error sentence is a dense run-on.

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 supplies the return shape ({ ok, endpoint_id, created }), the failure modes with codes (400, 402, 404) and their remediation, and the free-tier write constraint. Nothing an agent needs in order to call this correctly is missing, apart from the annotation mismatch noted elsewhere.

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 baseline would be 3, and the description adds real meaning on top: slug is normalized to lowercase [a-z0-9-] capped at 40 chars, it becomes both the monitor name and its identity, and the curl example shows extra query arguments (cron, tz, grace_sec) that the input schema does not expose. That extra semantics — plus the error names slug_invalido, cron_invalido, tz_invalida — genuinely helps an agent construct a valid call.

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 description states a specific verb and resource — 'Create a monitor on its first check-in' via a slug ping — and defines the identity rule (same slug = same monitor) plus the transport ('Works by GET or POST'). It never names the sibling it should be preferred over (create_endpoint, ping_ingest, signal_slug), so it falls short of full sibling differentiation.

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 context is strong on constraints — creation happens only inside the free tier or trial, retries are safe, past the tier you get a 402 — but it gives no routing guidance telling an agent when to pick this over create_endpoint or the other signal_* tools. The when-not is clear; the when-versus-alternatives is absent.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description's only added trait is that the call itself incurs no charge, which is genuinely useful metadata amid billing/buy_plan siblings, but it says nothing about freshness of prices or response shape.

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?

A single compact sentence, front-loaded with what the tool returns and followed by the cost caveat. Nothing is redundant and nothing is 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?

For a zero-parameter, annotation-rich lookup this is near-sufficient, but there is no output schema, so the description is the only place to learn what the response contains — and 'prices and free allowances' is vague about units, currency, or whether tiers/limits are included. One more clause on return content would close the gap.

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. The schema (empty object, additionalProperties=false) already tells the agent no arguments are accepted, and the description correctly avoids describing nonexistent inputs.

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 specifically what the tool returns: current public prices and free allowances. That is clear enough to separate it from the mutation siblings (buy_plan, cancel_plan) and from billing. It stops short of explicitly contrasting with list_plans or billing, so the boundary is inferable rather than stated.

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 phrase 'no charge' implies this is a free informational lookup, which nudges an agent toward it instead of purchase or billing tools. However, it never says when to use pricing versus list_plans or billing, and gives no conditions or exclusions. Usage is implied, not guided.

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 destructiveHint=false, yet the description says the tool 'record[s] the code' and 'leave[s] the failure for the cron' — i.e., it submits and persists a failure signal that downstream cron behavior depends on. A tool that records state the server later acts on is not read-only, so the description directly contradicts the annotation.

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?

It is short and front-loads the exit-status semantics, but the 0-vs-1-255 rule is stated twice in nearly identical wording ('0 behaves like a ping, 1-255 record the code as a failure' versus '`0` behaves exactly like a plain ping; 1 to 255 record the code and leave the failure for the cron'), so roughly half the text is redundant.

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 only two fully documented parameters and no output schema, the description supplies enough to call the tool correctly: the meaning of the exit code, the shell one-liner, and the resulting failure handling. Only the contrast with its signaling siblings is absent.

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 baseline is 3, but the description adds genuine meaning the schema lacks: what 0 means versus 1-255, and that nonzero codes are recorded as failures rather than merely rejected. The schema's 0-255/400 rule is restated, so the gain is real but partial.

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 description states a specific action (report a shell exit status) and explains the semantics of the value (0 = ping-like, 1-255 = recorded failure), which is clearer than the bare name. It distinguishes itself semantically from a plain ping, but never names or contrasts the close siblings (signal_fail, ping_ingest, signal_slug), so sibling differentiation is left to inference.

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 a concrete integration recipe (`curl -fsS $ORIGIN/in/ID/$?` at the end of a script) and explains the intended outcome for each case, including who handles the failure ('leave the failure for the cron'). It does not, however, say when to prefer this over signal_fail or ping_ingest, so the when-not guidance is missing.

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?

It goes well beyond the readOnly/idempotent/destructive annotations: it discloses that no e-mail is sent, no outbound call is made, that the ingest only records `alert_pending`, that the cron converts this within 5 minutes with reason "fail", and that alerts are capped at one per 24 hours (or alert_repeat_sec). That is exactly the kind of side-effect and timing information an agent cannot get from structured fields.

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?

The purpose is front-loaded and the paragraph is reasonably tight, but 'Failing is not proof of life either: the clock keeps running' is documentation prose that does not help an agent select or invoke the tool and slightly dilutes the signal.

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 compensates by describing what happens after the call (alert_pending recorded, alert produced within 5 minutes) and how repeats are throttled. For a one-parameter signal tool this is nearly complete, though it omits what the immediate call response looks like.

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?

There is a single required parameter and schema description coverage is 100% (the schema already says it is the Monitor ID from Monitor.ingest_url), so the schema carries the meaning. The description adds nothing about the `id`, which is acceptable at baseline but not above it.

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 opening sentence 'Record a failed run' gives a concrete verb plus the signal type, which an agent can map onto the monitoring domain and separate from signal_start/signal_slug by the 'fail' semantics. It stops short of explicitly contrasting itself with those sibling signal tools, so it is clear but not fully differentiated.

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 explains the downstream timing (alert dispatched on the next five-minute check) and the repeat cap, which implies when a fail signal is meaningful, but it never states when to choose this over signal_start, signal_exit_code, or signal_slug, nor any prerequisites. Usage is implied rather than guided.

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 description is unusually candid that 'the first signal of a new name creates its monitor' — a state-creating side effect — but annotations declare readOnlyHint: true, which directly conflicts with that disclosure. It also says nothing about what the call returns or what happens on rate limits/auth failure, leaving the agent to reconcile a mutation story against a read-only annotation.

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?

The routing rationale is front-loaded and useful, but 'the first signal of a new name creates its monitor' is stated twice in a four-sentence description, and the closing sentence largely repeats the second. There is real waste for a three-parameter tool.

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 signal-emitting tool with no output schema, the description covers the routing model, the monitor auto-creation rule, and inherited settings, which is enough to call it correctly. The only gap is what the response contains on success or failure.

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 slug, signal and ingestKey already carry descriptions. The prose restates them (name becomes the monitor name; start/fail/exit code) and adds only the contextual note that `cron`, `tz` and `grace_sec` inherit from the plain ping-by-name — marginal added value over the schema, which fits the baseline 3.

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 description names a specific verb and resource ('Send start, fail or an exit code by name, with the ingest key') and distinguishes this from the id-keyed routes by explicitly equating it to `/in/:id/start`, `/in/:id/fail` and `/in/:id/:exit_code`. It effectively separates itself from signal_start/signal_fail/signal_exit_code (id-based) without naming the sibling tools directly, which keeps it at a 4.

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 states the selecting condition plainly: 'for a fleet that only knows the ingest key: the job sends its name, not the monitor id.' That tells an agent when this is the right choice versus the id-based siblings. It never states a when-not or names an explicit alternative, so it stops short of a 5.

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 only carry the safety profile (readOnly, idempotent, non-destructive); the description goes well beyond them by disclosing that the call does NOT clear the dead-man clock, does NOT move `last_event_at`, and does NOT clear the miss counter, plus how duration is measured and when `reason: "too_long"` fires. That is exactly the non-obvious behavior an agent needs.

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?

Front-loaded and dense with real information, but it repeats itself: the dead-man-clock point is made twice ("does not clear the dead-man clock: a routine that starts and hangs still becomes a miss" and again "does not clear the miss counter, so a routine that starts and hangs still becomes a miss"). One of those sentences should be cut.

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 single-parameter signal with no output schema, the description covers the lifecycle semantics, the alerting edge case, method support (GET or POST), and the `rid` correlation requirement. It never says what a successful call returns or what an error looks like, which is a minor remaining gap.

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% and already documents `id`, so baseline is 3. The description adds meaning the schema lacks: the `?rid=` correlation parameter needed when runs overlap, and the consequence of omitting it (duration measured against the wrong start).

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 description clearly states the tool's action ("Says the run STARTED") and its role in the run lifecycle — opening a run that a later success closes. It distinguishes start from success/failure semantically, but never names the sibling signals (signal_fail, signal_exit_code, signal_slug) it should be chosen over, so an agent gets no explicit routing.

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 concrete conditions for correct use: pass `?rid=` on both ends when runs can overlap, and expect a `too_long` alert when `max_duration_sec` is exceeded. It also implies when NOT to rely on it ("start is not proof of life"), but never names alternative tools or states an explicit exclusion against siblings.

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 the crucial detail that the action invalidates the previously issued URL, which is exactly the kind of consequence an agent needs before calling a destructive tool.

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?

A single front-loaded clause states the action and the side effect with zero padding. Nothing could be removed without losing meaning.

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 one-parameter tool with no output schema this is nearly sufficient, but it omits how to obtain the new URL after rotation (presumably status_feed_url) and does not explain why guest_token is optional despite being described as private.

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% and guest_token is fully documented there, including its header usage and reuse rule. The description adds nothing about the parameter, so the baseline of 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?

The description states a specific verb and resource ("Rotates the status feed token") and its immediate effect. It implicitly separates itself from the sibling status_feed_url, but never names that sibling, so an agent must infer the pairing.

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?

There is no explicit when-to-use or when-not-to-use guidance. The consequence (old URL stops working) hints at a revocation scenario, but nothing tells the agent when to prefer this over status_feed_url or what prerequisites exist (e.g. owner auth).

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, idempotentHint and destructiveHint=false, and the description still adds substantive context: the feed token's authority is limited to reading status and cannot create, change or delete anything. It also discloses the real risk — anyone holding the link sees the dashboard, so it must be treated as a secret — which is exactly the kind of operational consequence annotations cannot express.

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 no waste: the resource and its formats come first, then the security constraint. Every clause carries information an agent needs.

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 one-parameter read tool with no output schema, the description covers what is returned (a URL, in JSON and RSS), the scope of the token, and the confidentiality requirement. It stops short of stating whether the URL expires or what status_feed_rotate does to an existing link, which matters for an agent deciding whether to cache or re-request it.

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% and the single guest_token parameter is fully documented in the schema, including the X-Guest-Token header. The description references owner scoping but adds no syntax, format or fallback detail beyond what the schema already provides, 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?

The description states a specific resource (a public status feed URL) and its two formats (JSON and RSS), scoped to all of the owner's endpoints. It is clear enough to distinguish from listing tools, but it never names its closest sibling status_feed_rotate, so the create-vs-rotate distinction is left to inference.

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?

Use is only implied: an agent can infer this is for obtaining a shareable read-only status link. There is no explicit 'use this when...' statement, no mention of when to prefer it over status_feed_rotate, and no note on whether the URL is stable or must be re-fetched.

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