LastPing

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

The description goes far beyond annotations by disclosing append-only behavior, the impossibility of editing or deleting notes, forced author attribution as 'agent', acceptance of notes on closed incidents, the 50-note cap, and the non-idempotent nature of the operation. This richly covers behavioral traits annotations alone do not express. There is no contradiction with 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?

The description is long, but it is front-loaded with the core purpose and every paragraph addresses a distinct behavioral or usage concern. It is justifiably detailed given the append-only and attribution requirements, though it could be tightened without losing value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with this level of behavioral complexity and no output schema, the description is remarkably complete. It covers success expectations, conflict behavior, closed-incident handling, author attribution, content requirements, and failure handling for oversized bodies, leaving no major ambiguity for an agent deciding whether and how to call 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 description coverage is 100%, so the schema already fully documents body and incident_id. The tool description does reinforce the source of incident_id and the preferred note style, but it does not add meaning beyond the schema's own parameter descriptions.

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 ('write back'), a specific resource (incident notes), and the core action: recording findings on an incident's page. It clearly differentiates this from sibling tools like list_open_incidents and list_incidents by focusing on adding a note rather than reading incident data.

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 is explicit about when to use this tool: after investigating an incident, using incident_id from list_open_incidents, and sending a note whether or not the problem was fixed. It also gives strong guidance about what not to do, such as omitting notes or pasting stack traces, and clarifies that multiple notes on the same incident are expected and valid.

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 discloses a critical behavioral trait beyond the annotations: the plaintext key is returned only once and cannot be retrieved again, requiring immediate storage. It also suggests the use of expires_at for short-lived keys. This adds real operational awareness.

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 brief and well-structured: it states the purpose, gives a critical security warning, and provides parameter guidance. Every sentence earns its place with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter creation tool with no output schema, the description covers what matters most: what is created, the one-time return of the plaintext key, the storage imperative, and optional expiry guidance. An agent has enough to invoke it correctly.

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 explains both name and expires_at. The description reinforces expires_at as a short-lived-key option but adds little new semantic 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 clearly states the action and resource: 'Create a new LastPing API key.' This distinguishes it from the sibling list_api_keys and revoke_api_key at a basic level, though it does not explicitly call out those alternatives.

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 usage is implied: use this to create a new API key. It gives helpful security context about storing the key and short-lived keys, but it does not explicitly say when not to use it or point to alternatives like revoke_api_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?

Beyond the annotations, the description discloses important behavioral nuances: unrelated fields are ignored, non-email kinds are immediately usable, email kinds start unverified and require a confirmation click before route attachment, and the tool returns the new channel id. These are exactly the side effects and preconditions an agent needs to know.

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?

Four sentences, each earning its place: purpose, field-selection rule, email caveat, and return-value usage. The most important scoping instruction is front-loaded, and there is no redundant wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 11 kind-dependent parameters and no output schema, the description covers the essential operational details: return value, email verification prerequisite, and how the result connects to set_route. It could have added a brief example or noted potential errors, but it is sufficient for correct selection and invocation.

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. The description adds meaningful parameter-level guidance by stating that fields must match the chosen kind and that unrelated fields are ignored, which helps agents avoid sending the wrong fields. It also explains the email-specific confirmation behavior for the address field.

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-resource pair ('Create a notification destination') and states what it is for ('monitors can route alerts to'), plus what it returns. It clearly distinguishes creation from sibling tools like update_destination, delete_destination, and list_destinations.

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 clear context for when to use this tool: when creating a new destination, and it differentiates the email flow from non-email flows. It doesn't explicitly say 'use update_destination instead for existing channels,' but the create-focused wording and return-id guidance make the intended use clear enough.

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 the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), and the description adds substantial context beyond them: the upsert overwrite semantics, the set-once ci_provider constraint, and the critical disclosure that the CI webhook secret 'is shown exactly once' and is never retrievable afterwards. The described upsert behavior is consistent with both idempotentHint (same slug converges) and destructiveHint (existing config can be overwritten), so there is no contradiction.

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?

Four sentences pack the core verb, the upsert caveat, the three archetype routings, and the one-time-secret warning with zero filler — every sentence earns its place, and the most decision-relevant facts (upsert, type routing, set-once) are front-loaded. It loses a point only because it is a single dense wall of text with no scannable structure; light bolding or bullets would improve it given the breadth it covers.

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 28-parameter create tool with no output schema and low annotation richness, the description covers the major decision branches an agent needs: which parameters to supply per monitor type, the upsert pathway, and the one-time return of the CI secret. The only notable gap is that it never states the general success return shape (e.g., the new monitor's id), mentioning only the 'updated' note and the secret; since no output schema exists, a sentence on the primary return value would round it out.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and every one of the 28 parameters already carries a rich schema-level description, so the baseline is 3. The tool description adds value on top by grouping parameters into the three usage scenarios (schedule_kind clusters, probe_url/probe_interval_s/probe_expected_* clusters, ci_provider/ci_workflow/ci_branch clusters) and by explaining why probe_expected_status/probe_expected_body matter ('a probe with neither only proves something answered'), which the schema states per-parameter but the description synthesizes.

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 and resource — 'Create a new LastPing monitor' — and immediately qualifies the scope with the upsert behavior ('or update an existing one if slug matches — returns 'updated' note on upsert'), which distinguishes it from the sibling update_monitor. It then names the three monitor archetypes (heartbeat/ci, http, CI-fed), leaving no ambiguity about what the tool produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong when-to-use routing: which parameter groups apply to heartbeat/ci vs http monitors, and the explicit statement that ci_provider 'is the ONLY place it can be set' — a direct exclusion that routes the agent to create_monitor rather than update_monitor for CI binding. It does not, however, explicitly name update_monitor as the alternative for editing a slugless existing monitor's fields, and it says nothing about when to prefer delete_monitor/pause_monitor/resume_monitor, so the when-not guidance is partial.

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 are all false, so the description carries the behavioral burden. It excellently discloses that pages are private by default, that public pages are served at unauthenticated URLs and expose monitor names, that slug conflicts return 409, that invalid check_ids return 400 with nothing saved, and that the free tier allows only one public page. This goes well beyond 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?

Three dense sentences with no filler. The purpose is stated first, followed by the primary use case and then the most critical behavioral caveat about privacy. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a create tool with four parameters and no output schema, the description covers the key context: when to use it, the privacy implications, failure modes (400, 403, 409), and how to handle the optional slug safely. An agent has enough information to invoke it correctly and avoid the most common mistakes.

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 meaningful decision guidance: omit slug unless a specific URL is requested, random slugs are safer, private is the safer default for visibility, and monitor names may be sensitive. These are important operational semantics not fully captured in the schema alone.

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 uses a specific verb ('Create') and resource ('status page') and immediately defines what a status page is: a single page showing current status and recent history of chosen monitors. This clearly separates it from sibling tools like update_status_page, delete_status_page, and list_status_pages.

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 explicitly states when to use the tool: when monitor health needs to be visible to someone who cannot log in to the project. It gives strong contextual guidance about privacy and visibility but does not explicitly name alternatives or state when not to use it, so it falls just 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?

The annotations carry only coarse hints (idempotentHint=true, readOnlyHint=false), but the description and the assertions contract disclose the full behavioral profile: grading is taken over from the monitor, failures are recorded as cause 'assertion' regardless of exit code, declarations are immutable with a conflict error on second call, malformed entries are rejected before anything is written, and purely negative declarations are flagged as self-defeating. The second-call conflict behavior refines rather than contradicts the idempotentHint — it specifies precisely what idempotency means here, so the agent gets accurate expectations.

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 main description is three sentences with zero waste: the commitment semantics in the first, the grading effect in the second, and call timing plus pointers to the contract and worked example in the third. It is front-loaded with the most decision-relevant facts before any deferral to the schema or sibling documentation.

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 high-complexity commit tool with no output schema, the definition covers when to call, what it does, the failure consequence, immutability, validation-before-write, and the evasion edge cases, while deferring the parameter contract to the schema and the worked example to get_ping_instructions. The only real gap is that a successful call's return value is never described, which is minor for a side-effect commit operation whose behavior is otherwise fully specified.

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%: rid and check_id are self-explanatory, and the assertions parameter is exhaustively documented with kinds, ops, dotted-path restrictions, the 20-entry cap, the positive-criterion requirement, and a concrete JSON-array-as-string example. The main description adds only routing context ('see the assertions argument for the full, immutable contract') plus the grading consequence, which is useful framing but not new parameter-level meaning — so the high-coverage baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Commit') and a precise resource (the criteria by which the run will be judged), immediately followed by the observable consequence: the run stops grading itself and unsatisfied criteria produce a FAILED run with cause 'assertion'. It is unmistakably distinct from every sibling tool, none of which declare run expectations, and the '/start ping' timing frames it within a specific lifecycle.

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?

Explicit timing guidance is given ('Call this right after your run's /start ping, before doing any work') and an explicit when-not-to-use is stated: 'simply never call this tool for a run, and the monitor's own check-level assertions (if any) stay in force unchanged' — naming the built-in alternative of doing nothing. It also routes the agent to get_ping_instructions' expectations_how_to for a worked example, leaving no ambiguity about when or how to invoke it.

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

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

The description goes far beyond the annotations by disclosing the ON DELETE SET NULL foreign-key behavior, explaining that monitors survive with 'ping history and incidents completely intact,' keep running 'on its existing schedule, no longer attributed to any agent,' and remain visible via list_monitors/get_monitor. It also flags that the action 'cannot be undone.' This complements the destructiveHint=true and idempotentHint=true annotations without contradicting them — no annotation contradiction.

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?

Every sentence earns its place: the core action leads, followed by the critical side-effect warning, visibility consequences, the two alternative operations, and the irreversibility note. There is no filler or redundant restatement; the length is justified by the non-obvious cascade behavior that genuinely needs explanation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive tool with no output schema, the description covers all decision-relevant context: what gets destroyed (the agent row only), what survives (monitors, ping history, incidents), what survivors look like afterward (unowned, still scheduled, still listed), and how to accomplish reattachment or full removal via update_monitor/delete_monitor. The only omitted details are edge cases like repeated-call behavior, but the idempotentHint annotation already communicates that expectation.

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%, with the id parameter already described as 'Agent UUID (from register_agent or list_agents),' so the schema carries the full semantic load. The description reinforces that the UUID targets the agent being permanently deleted, but adds no new format, source, or syntax details beyond what the schema already provides.

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+resource+scope: 'Permanently delete a LastPing agent from the registry by UUID,' which unambiguously defines the action. It also distinguishes itself from the closely related sibling delete_monitor by explicitly stating 'deleting the agent alone never does that' when referring to removing monitors, so an agent can tell the two apart immediately.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit alternative routing: 'To reattach a survivor, call update_monitor with agent_id set to a different agent's id or slug' and 'To also remove a monitor, call delete_monitor on it separately.' It also states a clear when-not condition — this tool never removes monitors — so an agent knows exactly when a sibling tool is required instead.

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 destructiveHint annotation, the description discloses critical cascade behavior: deletion removes the destination from every monitor's routing, and event types routed only to this destination silently stop notifying anyone. It also states irreversibility ('This cannot be undone'), adding meaningful context beyond the schema and 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 description is front-loaded with the core destructive action, then covers consequences, pre-deletion checks, and the temporary alternative. Every sentence contributes essential guidance for a destructive operation, with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's destructive and cascading nature, the description covers permanence, routing impact, silent notification loss, prerequisite checks, and alternative behavior. The absence of an output schema does not create a meaningful gap because the key context an agent needs before invoking deletion is thoroughly explained.

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 input schema already fully describes the single id parameter with 100% coverage, including how to obtain it via list_destinations. The description does not add further parameter-level detail, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Permanently delete a notification destination (channel).' It clearly differentiates from sibling tools like delete_monitor, delete_agent, and set_route by focusing on notification destinations and their routing side effects.

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 explicitly instructs when to avoid deletion: check which monitors route to the destination via get_monitor and reassign those event types first. It also provides the alternative for temporary changes: edit routes with set_route and keep the destination in place.

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 indicate destructive behavior, and the description goes further by adding 'cannot be undone,' which conveys irreversibility beyond the plain destructiveHint flag. It also clarifies the exact target by UUID, adding useful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no filler. The action and resource are front-loaded, and the irreversibility warning follows naturally. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter destructive tool with strong annotations and no output schema, this description is complete. It states what is deleted, how it is identified, and that the action is irreversible—enough for an agent to invoke it safely and correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already covers the single parameter fully: id is a string described as 'Monitor UUID.' The description repeats 'by UUID' but adds no additional semantic detail beyond the schema, so the baseline score 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 action ('delete'), a specific resource ('LastPing monitor'), and a specific identifier ('UUID'). It clearly distinguishes this from other deletion tools like delete_destination and delete_status_page.

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 implies use for permanently removing a monitor and warns it cannot be undone, but it does not explicitly contrast this with non-destructive alternatives like pause_monitor or snooze_monitor. Usage context is clear but exclusions and alternatives are not stated.

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 signal destructiveHint=true, and the description goes beyond that by disclosing irreversible consequences, immediate URL invalidation, and the precise non-effect on monitors. This is exactly the kind of behavioral context that helps an agent understand side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: the core action, the irreversible consequences, and the alternative for a non-destructive use case. The most important information is front-loaded, and there is no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple single-parameter destructive operation, the description fully covers what happens on deletion, what does not happen, and what to use instead. Combined with the schema and annotations, nothing essential is missing for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the id parameter fully described as 'Status page UUID, from list_status_pages.' The description adds no additional parameter-level meaning, but the schema already carries the burden, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Permanently delete a status page.' It also distinguishes the action from the related update_status_page tool by clarifying that this removes the shared view while leaving monitors unaffected, so an agent can confidently select the right 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 explicitly states when not to use the tool: 'To stop sharing without losing the page, set visibility to 'private' with update_status_page instead.' This provides clear routing to the alternative and gives a concrete condition that should trigger the alternative 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?

The description goes far beyond the annotations, which only state idempotentHint=true and destructiveHint=false. It explicitly discloses that the endpoint CREATES monitors, has no delete or update path, never pauses or edits, returns a three-way diff, leaves existing monitors completely unmodified, rejects the entire payload if any entry is invalid, and applies a 100-monitor cap atomically. This gives the agent a precise behavioral model well beyond the structured hints.

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 long, but the tool is complex and dangerous (it creates monitors with no delete path), so the length is largely justified. It is front-loaded with purpose and structured into clearly captioned sections (PROPOSE, THEN ASK; WHAT TO SEND; READ THE TIMEZONE; WHAT COMES BACK). A little repetition of the 'no delete' point exists, but it serves as emphasis rather than fluff.

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?

Despite having no output schema, the description fully explains the return shape (created/existing/orphaned) and all calling constraints: required source_kind/source_ref, supported kinds, timezone handling, size caps, duplicate rejection, batch atomicity, and the ability to send '[]'. It even tells the agent where to see already-discovered monitors (list_monitors). Nothing needed to call this 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?

Although the schema already covers 100% of the single parameter, the description adds crucial semantic meaning: source_ref must be stable between scans or every monitor looks new, schedule_cron must only be sent when a real cron expression is read, tz must be read from the host or asked of the user, and omitting a source reports it as orphaned rather than ignored. These are meaning-bearing details the schema alone does not convey.

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 and resource: "Turn a scan of a repository or a host into monitors: send every scheduled job you found, get back a diff of what was created, what already existed and what has gone missing." This clearly distinguishes the tool from siblings like create_monitor by framing it as reconciliation/diff discovery rather than one-off creation. The later contrast with list_monitors further sharpens its identity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong usage context: run it nightly, on every CI build, after every deploy, and only after proposing the change to the user ("PROPOSE, THEN ASK"). It also points to list_monitors as a way to see existing discovered monitors without calling this. However, it does not explicitly name create_monitor as the alternative for manual one-off creation, so the when-not-to-use guidance is implied rather than fully explicit.

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 mark the tool readOnly, idempotent, and non-destructive. The description adds valuable behavioral detail: secrets are not exported, and placeholders become Terraform variables the user must fill in. This goes beyond annotation coverage without contradicting it.

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-load the resource scope and output format, then state the key secrets caveat. Every sentence adds meaningful, non-redundant information.

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 export tool with three optional, fully documented parameters and no output schema, the description covers what is exported, the output format, adoption behavior, and the secrets handling. Nothing critical 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 input schema already documents all three optional parameters with 100% coverage, so the description does not need to repeat them. It adds no extra parameter-level detail, but none is needed given 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?

Description names the exact action and scope: export existing LastPing monitors, destinations, routes, alert templates, and status pages as Terraform HCL. It is clearly distinct from the sibling CRUD and monitoring 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?

The description makes clear this is for exporting existing resources into Terraform and adopting them via import blocks rather than recreating them. It does not explicitly discuss when not to use the tool, but the use case is well implied.

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, so safety behavior is covered. The description adds useful behavioral context by stating the return shape matches list_agents and includes the live status rollup, which is not inferable from annotations or the minimal 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?

Two focused sentences with no filler. The primary behavior is stated immediately, and the usage hints are concise and actionable.

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 tool, the description plus annotations and schema fully cover operation semantics, valid ID sources, and return-shape expectations. No output schema exists, but referencing list_agents' fields is sufficient context for an agent to understand the response.

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%; the id parameter is already described as 'Agent UUID (from register_agent or list_agents).' The description mostly repeats this in prose ('by UUID') without adding new format, validation, or default information, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get a single LastPing agent by UUID') and distinguishes it from list_agents by emphasizing 'single' and from mutation tools like update_agent/delete_agent. It also specifies the resource type and return-scope detail (same fields as list_agents, including live status rollup).

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 explicitly directs the agent to use list_agents to find valid IDs and register_agent to create one, making the typical read flow clear. It does not explicitly contrast with update_agent/delete_agent, but sibling names plus the read-only annotation make the intended use 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?

Annotations already declare the operation read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that by specifying the return shape (a map), enumerating the possible keys, and explaining the semantic of an empty result. This helps the agent interpret the response correctly.

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 compact and front-loaded: the operation is stated first, followed by the return format and key details, ending with an important edge-case interpretation. Every sentence adds distinct value and there is no redundant filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only tool with one documented parameter and no output schema, the description fully covers what an agent needs: what the tool returns, the allowed keys, and the meaning of an empty result. Nothing critical 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 only parameter, 'id', is already fully described in the schema as 'Monitor UUID' with 100% coverage. The tool description does not need to repeat this and does not add additional parameter semantics, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Get all custom alert message templates for a LastPing monitor.' It clearly identifies the product scope and the operation, and the mention of a map keyed by event-type distinguishes it from related mutation tools like set_alert_template.

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 implies this is the tool to inspect existing custom templates, especially with its note about empty results meaning built-in defaults. However, it never explicitly names the alternative set_alert_template or states when to use one vs. the other, so the guidance is only implied rather than explicit.

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 mark this as read-only and idempotent, and the description adds critical behavioral context: assertions, guards, and routes are absent when not configured, and the related write tools replace entire sets. This warning goes well beyond the structured annotations and prevents silent data loss.

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?

Although the description is longer than typical, every sentence earns its place: it states the core function, explains the three significant return fields and their absence semantics, and delivers a crucial pre-write warning. The key action is front-loaded and the warning is clearly structured.

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 read tool with no output schema, the description sufficiently covers what is returned, when fields may be absent, and why reading before writing is necessary. The single parameter is fully documented in the schema, so nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides full documentation for the single `id` parameter ("Monitor UUID"), so the description does not need to add parameter details. It reinforces that the lookup is by UUID, but this is a minor addition 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 states a specific verb and resource: "Get a single LastPing monitor by UUID," and clarifies it returns the full configuration including assertions, guards, and routes. This distinguishes it clearly from list_monitors and other monitor-related 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?

The description provides explicit when-to-use guidance: read this before update_monitor with assertions or guards, and before set_route. It also explains the consequence of not doing so, making the routing decision unambiguous and actionable.

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, and destructiveHint=false, so the description does not need to reassert safety. It adds meaningful behavioral context by explaining that the tool returns all mechanisms together, describes the universal protocol, and discloses the limitations of each mechanism (e.g., run_wrapper cannot send blocked or note). No contradiction with annotations 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?

The description is front-loaded with the core purpose, and it has logical sections for choosing among mechanisms. However, it is very long and dense for a one-parameter getter, mixing returned-field descriptions, decision routing, protocol details, and follow-on tool guidance into continuous prose. Every sentence contributes useful content, but the structure could be tighter.

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?

Because there is no output schema, the description carries the full burden of explaining what the tool returns and how to act on it. It covers all major return fields, names alternatives, gives prerequisites, warns about misuse, and connects to related tools like update_monitor and declare_run_expectations. An agent has enough context to select and invoke this tool correctly.

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 only one parameter, id, and the schema already fully describes it as 'Monitor UUID (from create_monitor or list_monitors)'. The description adds no new parameter-specific semantics beyond implicitly reinforcing that the tool should be called after create_monitor, 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 opens with a specific verb and resource: 'Get everything needed to make a monitor actually report' and lists the concrete return contents: ping URL, copy-paste snippets, and three reporting mechanisms. It clearly differentiates this from siblings by framing it as the post-create_monitor retrieval of reporting setup material.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance ('Call this right after create_monitor'), names the three internal options, and provides strong exclusion rules: Claude Code may use hook_install, other agents must not translate it, and command-launched processes should use run_wrapper. It also tells the agent to read expectations_how_to and discovery_how_to, so the usage context is fully specified.

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?

With readOnlyHint and idempotentHint already covering safety, the description goes far beyond annotations to explain field-presence semantics: ci_meta-only fields, steps matching on rid, exclusion of pings lacking both ci_meta and rid, and the critical provenance distinction between duration_ms (computed by LastPing) and duration_s (provider-reported). This is exactly the behavioral nuance an agent needs to interpret data correctly.

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 long (~180 words) but nearly every clause earns its place by preventing a real misinterpretation, such as conflating duration_s with duration_ms. The core scope is front-loaded, and the conditional-field detail follows logically. It is dense rather than bloated, though it could be tightened.

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?

There is no output schema, so the description carries the full burden of explaining return values — and it does so exhaustively: run fields, conditional presence rules, exclusion criteria, and cross-field relationships. For a tool with this much conditional complexity, nothing an agent needs to interpret the response 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% for both parameters (id as Monitor UUID, limit with default/max), so the schema carries the full burden. The description adds context about what a run contains but not about the parameters themselves, landing 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 description names a specific verb ('Get') and resource ('structured run history for a monitor') and immediately distinguishes the two run kinds it covers: CI/CD runs and agent/heartbeat runs. This is precise enough to separate it from sibling list/get tools without opening schemas.

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 implies usage context well — it explicitly teaches the agent how to answer 'how long does this job normally take?' for a non-CI monitor via duration_ms. However, it never names an alternative or states when NOT to use this tool, so routing guidance is left to inference rather than stated.

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, and non-destructive behavior, so the description does not need to restate safety. It adds valuable behavioral detail beyond annotations: status is a live roll-up from the agent's monitors, ordered worst-first, with each possible value explained. This is essential context for interpreting results, especially given the absence of an 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 purpose is front-loaded in the first sentence, return fields are listed, and the status semantics are explained compactly but thoroughly. The final sentence routes to register_agent without adding noise. Every sentence earns its place, and the status enumeration is necessary because the status field has custom domain 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?

This is a zero-parameter read-only list operation with annotations covering safety. The description supplies the return fields and the complete semantics of the status field, which compensates for the missing output schema. An agent has everything needed to invoke the tool and interpret its response correctly.

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 has zero parameters and 100% schema description coverage, so there is no parameter burden for the description to carry. The phrase 'registered in the project' adds scope context but no parameter-specific documentation is needed.

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 ('List'), the resource ('agents registered in the project'), and the exact fields returned, including the nuanced status field. This makes it clearly distinguishable from siblings like get_agent (single lookup) and register_agent (creation).

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 explicitly names register_agent as the alternative when the goal is to create an agent. It does not explicitly contrast with get_agent for single-agent retrieval, but the phrase 'List all agents' makes the usage context clear without requiring an exclusion statement.

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 mark the operation as read-only and idempotent, but the description adds substantial behavioral detail: it never returns plaintext values, includes last_used_at and last_used_surface, omits those fields for unused keys, and explicitly warns that last_used_surface is spoofable and not a trust boundary. This is exactly the kind of context an agent needs beyond structured 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?

Every sentence earns its place: the core action, the security boundary, the field semantics, and the spoofability caveat. The most important information is front-loaded, and the length is justified by the nuanced security warning about caller-controlled User-Agent data.

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 list operation, the description covers the key return values, their absence behavior, and a security caveat. No output schema exists, so this descriptive coverage is sufficient for an agent to call the tool correctly and interpret results appropriately. The annotations cover safety, and the description covers behavior.

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 input schema has zero parameters, so there is nothing for the description to explain about parameter usage. The description appropriately clarifies that the call lists all keys in the project without filtering, and it documents the meaning of fields returned. With no parameters, this is effectively complete.

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 and resource: 'List all API keys in the project.' It goes beyond a generic listing by clarifying the security-relevant behavior of returning only non-secret prefixes, which also distinguishes it from create_api_key and revoke_api_key. This is unambiguous and clearly scoped.

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 it clear this is the read-only listing tool and explains that the returned prefix is sufficient for a subsequent revoke_api_key call. It does not explicitly enumerate when not to use it, but the context strongly implies this is the appropriate tool for identifying existing keys without exposing secrets.

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 assert readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only safety profile is known. The description adds the project scope and channel type enumeration, and claims 'all', but offers no detail on response structure, pagination, or ordering. This is useful but not rich behavioral context.

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 with no filler. The main action and scope are front-loaded, followed by a purpose statement. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless list tool, the description covers what is listed, the project scope, and the downstream use of channel IDs. Since no output schema exists, an explicit return-format note would strengthen it, but the description is largely sufficient.

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 accepts zero parameters, so the input schema is fully descriptive. Baseline 4 applies; the description adds no parameter detail because none is needed.

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 ('List') and resource ('notification destinations (channels)'), scopes to 'in the project', and enumerates channel types. The final clause ties the output to routing rules, clearly distinguishing it from sibling tools like create_destination or delete_destination.

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 sentence 'Use channel IDs to configure routing rules for monitors' gives a concrete usage context. However, it does not explicitly state exclusions or alternative tools, so it stops short of the fullest 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 cover read-only, idempotent, non-destructive behavior, so the safety profile is accounted for. The description adds useful behavioral context beyond annotations: results are returned newest first, and open incidents are identifiable by closed_at=null. This is meaningful operational information for an agent interpreting the output.

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 three short sentences with no filler. It front-loads the core purpose, then the ordering behavior, then the open-incident convention, so every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple read-only list operation, the description covers the essential behavior: what is listed, for which resource, in what order, and how open incidents are represented. Pagination or time-window details are not mentioned, but the limit parameter is already in the schema and annotations cover safety, so the gaps are minor.

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 input schema documents all parameters with 100% coverage: id is a Monitor UUID and limit has a default of 50 and max of 200. The description adds no parameter-specific details beyond the schema, so it meets the baseline without adding extra semantic value.

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 ('List'), a specific resource ('incidents'), and scopes it to a monitor, while clarifying that incidents are downtime events. It also notes that open incidents have closed_at=null, which helps distinguish from the sibling list_open_incidents, though it never explicitly names that alternative.

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 implies this is the general incident listing tool that includes both open and closed incidents, and it is clearly tied to a monitor context. However, it does not explicitly state when to prefer list_open_incidents or provide any exclusions or conditions, leaving the usage guidance largely inferable.

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 provide readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it specifies the project scope, the exact return fields, and the tag-filtering behavior. No pagination or ordering details are given, but this is minor for a simple list 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?

Two concise sentences with no filler. The main action is front-loaded, the return payload is stated immediately, and the parameter guidance is included without redundancy. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with one optional parameter and no output schema, the description is complete: it names the scope, lists the returned fields, and explains filtering. The annotations cover safety, and the missing details like pagination are not critical given the tool's simplicity.

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 schema already documents the optional tag parameter with an example and expected effect. The description repeats this in slightly different words ('filter by a single tag') but adds no meaningful meaning beyond the schema, 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 ('List'), a clear resource ('monitors'), and the scope ('in the authenticated LastPing project'). It also enumerates the returned fields (id, name, slug, status, ping_url), making the tool's purpose unmistakable and distinguishable from sibling monitor tools like get_monitor or update_monitor.

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 clearly implies the tool is the list/filter operation and explains how to use the tag parameter, but it never explicitly contrasts it with alternatives such as get_monitor for a single monitor or mentions when not to use this tool. Usage context is present but relies on inference from sibling names.

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, and non-destructive behavior, and the description adds substantial extra context: it explains the meaning of missing fields, that absence is evidence of absence rather than success, the difference between 'fail' and 'silence', and the semantics of exit_code 0. This goes far beyond what annotations provide.

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 long but well-structured: it front-loads the core purpose, then uses a bulleted list to explain why each payload field matters. Some rhetorical framing is present, but nearly every sentence adds signal, and the organization makes the detail digestible.

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?

There is no output schema, so the description carries the full burden of explaining return semantics, and it does so thoroughly: it names the key fields, explains what they mean, clarifies absence behavior, and even describes the recommended follow-up action. For a read-only tool with fully documented parameters, nothing essential is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents agent_id and limit, including defaults, max, and newest-first ordering. The description reinforces the 'newest first' behavior and the agent-owned scope, but it does not add much new parameter-specific meaning 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 opens with a precise verb and resource: 'Read this agent's failure inbox' and further scopes it to incidents that are currently OPEN on monitors the agent owns, newest first. This clearly distinguishes the tool from broader list_incidents and other siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to call this tool at the START of a run, before doing work, and explains its role as the way an agent discovers what broke while it was not running. It also instructs to follow up with add_incident_note, though it does not explicitly state when not to use the tool or name list_incidents as an alternative.

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 mark it read-only, idempotent, and non-destructive. The description adds meaningful behavioral context beyond that: the returned fields, the public-URL caveat, and the replacement semantics relevant to update_status_page. No contradictions with 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?

Three sentences with each earning its place: output fields, conceptual definition, and critical interaction with update_status_page. The most actionable information is front-loaded.

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 no-parameter, read-only list tool with no output schema, the description covers purpose, returned fields, the domain concept, and the key usage caution. Nothing essential is missing for an agent to call it correctly.

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 has zero parameters, so the schema fully covers parameters and the description has no burden to explain them. The baseline of 4 applies because no parameter information could improve the description.

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 and resource ('List the project's status pages') and enumerates the exact fields returned: id, slug, title, monitors, visibility, and public URL. This makes the tool's purpose immediately distinguishable from list_monitors and list_incidents.

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 usage scenario: this is the read to perform before update_status_page, because update's check_ids replace the monitor set. It does not explicitly mention when not to use it or name alternative list tools, so it is not a full 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 already state readOnly=false, idempotent=true, and destructive=false. The description adds valuable behavioral context by explaining the paused=true state, that pings continue to be received, and that alerting ceases—useful beyond the annotations and no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the key action and effect front-loaded. Every clause earns its place; no filler or redundant restatement of the tool name.

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, no-output-schema tool with annotations covering safety and idempotence, the description is largely complete. The only notable gap is not placing pause in relation to the sibling snooze/resume tools, but an agent can still invoke it correctly with the given information.

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 only parameter, id, is already documented as a Monitor UUID. The description does not add extra param detail, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action (pause a LastPing monitor) and the intended effect (stops alerting, paused=true). It distinguishes from destructive actions like delete_monitor, though it doesn't explicitly contrast with snooze_monitor, so it falls just 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 usage context is implied: use when you want the monitor to keep receiving pings but stop alerting. However, no alternative tools are named, and there is no explicit when-not-to-use guidance such as comparing with snooze_monitor or resume_monitor.

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 are all false, so the description carries the full burden. It goes beyond basic 'register' semantics by disclosing return values (id, slug, wire-up instructions), duplicate-slug rejection behavior, the 400 UNKNOWN_AGENT error, and the safety of re-registering with the same name. No annotation contradiction 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?

The description is longer but every sentence earns its place. It front-loads the core purpose and return value, then adds the one-time usage rule, attachment rule, and error semantics in a clear labeled structure. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description explicitly names what is returned (id, slug, wire-up instructions). It also covers the critical workflow context: how to attach monitors, re-registration behavior, and error cases, making it complete for an agent to call this tool correctly.

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%, providing baseline 3. The description adds valuable extra semantics for the name parameter: it derives a stable slug, duplicate slugs are rejected, and re-registering with the same name is safe. The description parameter is adequately covered by the schema's own description.

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 a specific verb and resource: 'Register a new autonomous agent in the project's agent registry, returning its id, slug and wire-up instructions'. It also distinguishes itself from related tools by explicitly noting it is not an implicit create and by providing an attachment rule tied to create_monitor.

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?

Provides explicit when-to-use guidance: 'Call this ONCE per autonomous worker, not once per monitor.' It also explains the exact relationship with create_monitor: pass the returned agent_id (id or slug) to create_monitor's agent_id parameter, and warns that naming a non-existent agent is an error and never an implicit create.

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 indicate this is a non-read-only, idempotent, non-destructive action. The description adds useful behavioral context by specifying the state transition ('paused=false') and the timing of alerting resumption.

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 concise sentences carry the full meaning: the action, the target state, and the behavioral consequence. No filler or redundant detail.

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?

This is a simple one-parameter mutation with annotations covering safety and idempotency. The description covers the state change and future alerting behavior, so an agent has everything needed to call it correctly.

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 only parameter, id, is already documented as 'Monitor UUID.' The description does not need to add parameter meaning and does not add anything 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 states a specific verb ('Resume'), a specific resource ('a paused LastPing monitor'), and the resulting state ('paused=false'). This clearly distinguishes it from siblings like pause_monitor and snooze_monitor.

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 that the tool applies to paused monitors and that alerting resumes on the next missed ping. It does not explicitly discuss alternatives or exclusions, but the usage context is unambiguous.

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

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

The description adds meaningful behavioral detail beyond the annotations: revocation is permanent, takes effect immediately, and cannot be undone. It does not contradict the destructiveHint or idempotentHint annotations, and it clarifies the real-world consequence for the agent.

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 two crisp sentences with no filler. It front-loads the action and permanence, then immediately covers the behavioral consequence and replacement need.

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 destructive tool, the description and schema together cover what the tool does, what the argument means, where to find it, and what happens after execution. No output schema is needed to make the call behavior understandable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the schema already explaining that api_key_id is a UUID and where to obtain it. The tool description adds no additional parameter-specific meaning, 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 ('revoke') and resource ('API key'), and clearly conveys the permanent, immediate effect. This distinguishes it from sibling tools like create_api_key and list_api_keys without requiring schema inspection.

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: if a key must be permanently invalidated, use this tool. The description notes that a replacement key must be created, which hints at the create_api_key sibling, but it does not explicitly name that alternative or state when not to use this 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?

The description goes far beyond the annotations. It discloses validation against allowed variables, the reset-to-default behavior for empty strings, the read-modify-write merge behavior that preserves other templates, and detailed provider-dependent caveats for {failing_stage} and {body}. Annotations already include destructiveHint=true and idempotentHint=true, and the description is fully consistent with those traits rather than contradicting them.

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 long, but nearly every sentence earns its place by explaining validation, reset semantics, read-modify-write behavior, variable availability, and provider caveats. The main sentence is front-loaded with the core purpose before diving into details. The variable list could arguably be shortened, but it is immediately useful and not 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 mutating tool with no output schema and a moderately complex template parameter, the description covers side effects, concurrency behavior, validation requirements, reset semantics, and important environment-specific variable limitations. There are no significant gaps that would prevent an agent from using the tool correctly.

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 substantial value beyond the schema: it enumerates all allowed template variables, explains the semantic meaning of {body} via pings.body_excerpt, and details CI-provider behavior for {failing_stage}. This materially improves the agent's ability to construct a valid template parameter.

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-plus-resource statement: 'Set or clear a single alert message template on a monitor.' It clearly distinguishes this from the read-only sibling get_alert_templates by emphasizing 'set or clear' and 'single' template, so an agent can immediately identify the operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear operational context: when to pass an empty string, that this is a read-modify-write preserving other templates, and that a custom template is the only way to control where {body} appears. It does not explicitly name an alternative tool such as get_alert_templates for reading, but the contrast is strongly implied and the context is sufficient for 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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description amplifies them with concrete context: the whole set is replaced, destinations configured by others are silently dropped, empty channel_ids clears routing. It even discloses downstream behavioral nuances (rate caps, blocked's protected budget, GitHub double-starts), far exceeding what annotations convey. No contradiction with 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 main description is tightly front-loaded with the most critical fact (whole-set replacement) in caps, followed by prerequisites and edge cases. The event_type parameter text is long (~380 words), but nearly every sentence carries operational knowledge an agent needs to route safely; a small deduction for verbosity in the rate-cap explanation.

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 3-parameter tool with no output schema, the description covers the action, the destructive semantics, preconditions (verified/enabled destinations, email confirmation), how to obtain IDs and current routing, clearing behavior, and deep guidance on event-type selection. Nothing an agent needs to invoke this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, setting a baseline of 3, but the description adds substantial operational meaning beyond the schema: the event_type parameter is enriched with state-change vs. informational categorization, chatty-event rate-cap grouping, and the blocked-event budget rationale, which materially changes how an agent selects event types. The channel_ids semantics (pass existing IDs plus new one; empty string clears) are also spelled out beyond the schema's literal text.

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: 'Route a monitor's alerts for one event type to a set of destinations (channels).' This distinguishes it from siblings like get_monitor (reads routes), list_destinations (enumerates destinations), and update_monitor (monitor settings), by making the exact scope — one event type, full destination set — explicit.

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 explicit workflow directives: 'CALL get_monitor FIRST and read its routes field' and 'Use list_destinations for IDs.' It also warns against the partial-update mental model ('adding a destination means passing the existing ids PLUS the new one'), which functions as when-not-to-use guidance for a destructive replace operation.

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 indicate this is a mutating, idempotent, non-destructive operation. The description adds useful behavioral context beyond the annotations: during the window, alerts are suppressed, and clear=true removes the window. It does not contradict any 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?

Two concise sentences lead with the primary action, then give the required exclusivity rule and examples. Every sentence adds value, and the structure is easy to parse quickly.

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 4-parameter mutation tool with full schema coverage, no output schema, and annotations covering safety and idempotency, the description is essentially complete. The main missing piece is return behavior, but that is not required to invoke the tool correctly.

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 each parameter already has a descriptive schema comment. The description reinforces the 'exactly one of' relationship and provides examples for duration, but does not add meaning beyond what the input schema already states.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Set or clear a maintenance window') on a specific resource ('a monitor') and explains the observable effect ('the monitor will not alert'). It is clear even among siblings like pause_monitor and resume_monitor, though it does not explicitly differentiate itself from those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear operational constraints: 'Provide exactly one of' duration, until, or clear=true. However, it does not explain when to choose snooze_monitor over related sibling tools such as pause_monitor or resume_monitor, leaving the selection context mostly implied.

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, the description discloses the default synthetic LastPing alert behavior, the 400 error for non-email destinations with resend_verification, and the idempotent verified-state behavior. The idempotentHint=false annotation is not contradicted because the default test-alert path is not idempotent, while the description specifically limits idempotency to resend_verification on verified destinations.

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 dense but every sentence carries decision-relevant information, and the core action is front-loaded in the first sentence. The length is justified by the two-mode behavior (test alert vs. resend verification) that the agent must distinguish.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two modes, no output schema, and a closely related create_destination sibling, the description covers invocation, mode selection, error conditions, and repeat safety. An agent can decide whether to call this tool and with which flag without needing additional 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 description coverage is 100% and the schema already documents both parameters, including id source, the instead-of-test-alert behavior, email-only restriction, 400 error, and idempotency. The description repeats this semantic context but does not add new parameter-level meaning beyond the schema, so the baseline score 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 action and resource ('send something through a destination') and the intended outcome ('move it from created to known to work'). It distinguishes this from create_destination and other destination siblings by positioning it as the post-creation verification step.

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 explicitly tells when to use the default test alert ('after create_destination to confirm the credentials are right') and when to use resend_verification instead (when create_destination reported UNVERIFIED and the confirmation email never arrived or expired). It also warns that a test alert is useless for unverified email destinations, giving a clear exclusion.

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 goes well beyond the annotations, explaining exactly what merge-patch semantics mean, that omitted fields retain their current value, and that the slug is immutable so existing references (including monitors attached via agent_id) keep working. This meaningfully enriches the idempotentHint and destructiveHint annotations and sets accurate expectations.

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 well-structured sentences with no filler. The core operation is front-loaded, and the second sentence adds critical behavioral nuance about slug immutability. Every word contributes to correct invocation.

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 small 3-parameter update operation with no output schema, the description covers the important caveats: merge-patch semantics, the safe default for name-only renames, how to clear description, and why the slug remains stable. Nothing critical is missing for an agent to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents id, name, and description with helpful examples. The description reinforces the merge-patch behavior but does not add much new per-parameter meaning beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb ('Update'), a specific resource ('existing LastPing agent'), and the target fields ('name/description by UUID'). It is immediately distinguishable from sibling tools like register_agent, delete_agent, and get_agent.

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 clearly establishes when to use this tool: to modify an existing agent's name or description. It also gives practical usage guidance on merge-patch behavior (omit to keep, empty string to clear) and notes slug immutability. It does not explicitly name alternatives like register_agent for creation, but the context is clear enough.

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, the description discloses important behavioral details: the operation is in-place and partial, the kind is immutable, and changing an email address resets verification and triggers a new confirmation email. This adds meaningful side-effect context that the annotations alone do not provide.

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 concise sentences deliver the core action, the key limitation, and the most important side effect. Every sentence earns its place and the most critical information is front-loaded.

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 mutating tool with a nested config object and no output schema, the description plus the detailed schema provides all necessary information for an agent to call it correctly: what updates, what cannot change, how to handle config, and the email-specific consequence.

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 input schema already documents all parameters with high coverage, including detailed config shapes, so the baseline is 3. The description adds value by explaining that only passed fields are changed and by highlighting the email verification reset, which affects the config parameter's 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 description clearly states the verb and resource: 'Update a notification destination's name and/or config in place.' It also explicitly distinguishes itself from create/delete operations by noting that the destination kind cannot be changed and must be deleted and recreated instead.

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 explicitly explains when this tool should not be used: changing the destination kind requires 'delete and recreate instead.' It also clarifies partial-update semantics with 'Only the fields you pass are changed,' which guides an agent on how to construct a correct call.

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 (readOnlyHint=false, idempotentHint=true, destructiveHint=true) already frame this as a read-write, idempotent, potentially destructive update. The description goes well beyond them: merge-patch semantics, replace-the-set behavior for tags/assertions/guards, slug and ci_provider immutability, and the delete/recreate consequence. It even explains WHY the destructive capability exists (guards catch looping agents burning money), which is exactly the behavioral context that changes how an agent exercises the 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 ~170-word paragraph with no wasted sentences: every clause (merge-patch, tags replacement, slug immutability, assertions/guards role, ci_provider immutability) is load-bearing for a 28-parameter tool, and the core semantics are front-loaded. It loses the top score only because it is one dense unbroken block of text with no bullets or paragraph breaks, which taxes scannability.

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 28-parameter mutation tool with no output schema and no auth/rate-limit annotations, the description covers the operation's semantics thoroughly: what changes, what replaces wholesale, what is immutable, and what the delete/recreate fallback is. The main gap is that it never states the return value or any permission/rate-limit expectations — with no output schema present, one line on what the call returns would make it fully self-sufficient.

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 per-parameter burden is already carried by the schema — baseline 3 applies. The description adds a layer the schema cannot express as a whole: global merge-patch semantics ('any field you omit keeps its current stored value'), the replace-the-set rule spanning tags/assertions/guards, and the immutability of slug and ci_provider — facts about fields that do not even appear as parameters in the schema. That is meaningful additive value, while per-parameter details are correctly left to 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?

States a specific verb and resource — 'Update an existing LastPing monitor's schedule/config by UUID' — and layers on the defining semantic (merge-patch) that separates it from siblings like create_monitor, delete_monitor, pause_monitor, and resume_monitor. It also advertises two responsibilities an agent would not guess from the name alone: this is the tool that sets output assertions and metric guards, with explicit 'how a job that exits zero... gets caught' motivation.

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?

Provides clear operational context plus an explicit when-not: 'rebinding a monitor to a different CI system means deleting and recreating it' because ci_provider is immutable, which routes the agent to the delete/create sibling pair. It also scopes what CAN be changed here ('only its ci_workflow/ci_branch filters can be changed'), but it never systematically enumerates when to prefer create, pause, resume, or snooze over this tool, 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?

Discloses merge behavior ('reads the page first and merges'), replace semantics for check_ids, destructive slug changes that break public links, and privacy consequences of visibility='public'. This adds substantial context beyond the annotations and aligns with destructiveHint=true.

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 the core update behavior, and every sentence contributes a distinct rule or warning: partial updates, replacement semantics, link breakage, and public visibility risks. It is appropriately detailed for the tool's complexity.

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 five-parameter tool with destructive effects and no output schema, the description covers merge behavior, replacement, error conditions, data sources, and privacy caveats. An agent has enough context to select and invoke this tool correctly without additional documentation.

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. The description adds cross-parameter insight: how to add one monitor by combining existing ids from list_status_pages with the new id, and that omitting check_ids can never blank the page. This meaningfully increases utility beyond the schema field descriptions.

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 the operation explicitly: update a status page's title, slug, visibility, or monitor set. Names the resource and specific fields, and is clearly distinct from create_status_page, delete_status_page, and update_monitor.

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?

Provides strong usage context: only pass fields you want to change, omit to preserve current values, and pass existing ids plus a new monitor to avoid blanking the page. It does not explicitly name create/delete alternatives, but the partial-update and replacement semantics make when to use this tool clear.

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