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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds value by listing the exact fields returned, which goes beyond what annotations convey. It also clarifies what is not included (plan/limit info). 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?

Two sentences: the first states purpose and lists fields, the second provides an exclusion and alternative. Every sentence earns its place, information is front-loaded, and there is no 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?

For a no-parameter read tool with no output schema, the description enumerates the returned fields and clarifies what is not included. It provides enough context to invoke and interpret results, covering the essential contract for a simple getter.

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 0 parameters, so parameter description is unnecessary. The description contains no parameter info, which is appropriate for a parameterless tool; the baseline for 0 params is 4.

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 ('Returns'), a specific resource ('profile of the current account'), and enumerates the included fields (id, email, name, status, avatar, etc.). It explicitly excludes plan/limit info and names the sibling `current_plan_get`, distinguishing it from other account 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?

It explicitly says when not to use it ('Plan/limit info is not here') and points to the correct alternative (`current_plan_get`). It does not mention other siblings like `account_update` or explicitly state 'use this when you need the current account profile', but the description itself defines the use case clearly.

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 convey write and destructive potential, so the description adds the valuable 'partial update' semantics and the exact mutable-field whitelist. It does not describe the confirm authorization override, but it does not contradict 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 two sentences, front-loads the core partial-update behavior, lists the relevant fields, and ends with a direct usage instruction. No filler or redundancy.

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 partial-update tool with annotations covering destructiveness and a schema that documents the confirm override, the description is sufficient for correct invocation. It does not explain return values, but no output schema exists and the update semantics are clear.

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 low (25%), but the description compensates by identifying which schema properties are mutable and by instructing that omitted fields remain unchanged. This adds real meaning beyond the bare property names and types.

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 ('Partial update') and resource ('account profile'), and goes further by naming the mutable fields. This clearly distinguishes it from account_get and other account/profile-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?

It gives clear context for use: update profile fields and pass only those you intend to change. It does not explicitly mention alternatives such as account_get for reads, but the usage intent is unambiguous.

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

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

Annotations cover read-only and open-world hints, but the description goes well beyond them: 50,000 row cap, truncated true semantics, plan gating with error code, the export being recorded as activity_log.export, and the CSV column list. This is substantial context for a read-only export and does not contradict the readOnlyHint.

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?

Dense but well-organized: action first, then filters, columns, limits, plan gate, side effect, and usage preference. The column list is justified because there is no output schema, and every sentence carries operational 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 8 parameters, plan gating, a truncation contract, and no output schema, the description covers all operational essentials: what it returns (CSV columns), how much it returns, how to handle truncation, when it fails, and when to prefer activity_log_list. Nothing required for correct invocation 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 schema already documents all 8 parameters at 100% coverage, so the description doesn't need to redefine them. It adds meaningful semantics by pointing to the sibling filter set ('same filters as activity_log_list'), clarifying that pagination is ignored, and advising to narrow from/to or filters when truncation occurs.

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: 'Downloads the activity log as CSV', and immediately distinguishes it from activity_log_list by noting it uses the same filters with pagination ignored. It also states when it should not be used ('Prefer activity_log_list for questions'), so an agent can tell it apart from sibling 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?

Explicit guidance is given: 'Prefer activity_log_list for questions — use this tool only when the user explicitly wants a file or a full dump.' It also documents the plan prerequisite and the exact failure code (activity_log_export_unavailable), leaving no ambiguity about when the tool applies.

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 include readOnlyHint and openWorldHint, and the description adds substantial behavioral detail: newest-first ordering, entry structure (action, actor, source, target, masked changes, details, ip, location), and constraints (retention_days, support staff never included). It also mentions 'masked changes' implying redaction. 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 description is detailed but efficient: it leads with the purpose, gives concrete example questions, then outlines the response structure and key limitations. Every sentence adds value, 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?

With no output schema, the description fully explains the response fields (action, actor, source, target, masked changes, details, ip, location) and the retention_days field. It also covers edge cases (plan window limits, support staff excluded). For a list tool with 10 optional parameters, this is complete.

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

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

Schema description coverage is 100%, so every parameter is already documented. The description reinforces the action code format and search semantics but does not add new parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate given the high schema coverage.

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

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

The description explicitly states the tool returns the account audit log newest first, specifying the content (who changed what and when) and sources (panel, bots, API keys, system). It is clearly distinct from siblings like activity_log_export, which presumably handles exports. The verb 'list' plus resource 'activity log' is precise.

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 context on when to use it via example questions ('who paused this server', 'when was the account logged into'), and notes limitations (plan window, support staff excluded). It does not explicitly name alternative tools or state when not to use it, but the purpose is clear enough to route an agent correctly.

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 readOnlyHint annotation already signals no state modification. The description adds behavioral context by listing the returned subscription fields and framing the tool as a gating check, which helps the agent understand its role. It does not over-promise side effects, staying consistent with the read-only annotation.

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

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

Two sentences, no filler. The first sentence lists the return contents with useful field names, and the second provides a practical purpose. Every sentence contributes.

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, read-only getter, the description is complete. It names the output fields, explains the gating use case, and the annotations cover side-effect safety. No output schema is present, but the field listing compensates adequately.

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 baseline is 4. The description adds value by documenting the shape of the response payload, including the features object and subscription metadata, even though it does not describe parameters (there are none).

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 begins with a concrete verb and resource: 'Returns the active plan'. It enumerates exactly what is returned (price, features object, subscription metadata) and names the specific fields (`valid_until`, `current_billing_period`, `pending_plan`). The title reinforces the resource, and the description clearly distinguishes this from a generic plan list by focusing on the current plan.

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 an explicit use case: 'Useful to check gates before calling feature-restricted endpoints.' This tells the agent when to call the tool. It does not explicitly name alternatives like plan_list or state when not to use it, but the use case is concrete 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 indicate readOnlyHint, and the description adds meaningful behavioral context: while holiday mode is active, personal incident notifications are suppressed but checks and incident recording continue. This goes beyond the structured annotations and helps the agent understand the operational impact of the returned state.

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: it states the primary return value first, explains possible values, and then provides the behavioral consequence. Every sentence adds value and there is no redundancy.

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, read-only status getter with no output schema, the description gives the return shape, the null semantics, and the real-world effect of the mode. Nothing critical is missing for an agent to invoke and interpret the result 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 carries no parameter burden. The description adds semantic meaning to the output field and explains the null case, which is useful and complete for a parameterless getter.

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 ('returns') and a specific resource ('holiday/vacation mode'), and also explains the value of the returned field (`holiday_until`). This distinguishes it from the sibling `holiday_mode_set` without ambiguity.

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?

Although it does not explicitly name an alternative tool, it gives clear context for when this read-only status check is useful and explains what the state means. The sibling `holiday_mode_set` is obviously the complementary mutation tool, so usage context is reasonably clear.

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

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

Beyond the annotations, the description adds valuable behavioral detail: 'While active, personal notifications are suppressed; monitors keep running and incidents are still recorded.' This clarifies the boundary of side effects and reassures an agent that monitoring and incident capture remain unaffected.

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 deliver the action, the input condition, and the behavioral consequences with no filler. The enable/disable logic is front-loaded and immediately 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 simple two-parameter setter with no output schema, the description covers the input semantics and the observable effects of the mode. The confirm behavior is documented in the parameter schema, and no additional context is needed 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%, and the description mostly restates what the schema already says: holiday_until is an ISO 8601 timestamp, and omitting it disables holiday mode. The confirm parameter is well documented in the schema, so the description adds no significant new parameter meaning.

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

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

The description states a specific verb-resource pairing: it 'Enables holiday mode until the given timestamp' or 'disables it if holiday_until is omitted.' This clearly distinguishes it from the sibling holiday_mode_get and from other monitor/incident 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 conditional phrasing gives clear usage context: call this to enable holiday mode with a future timestamp, or omit the timestamp to disable it. It does not explicitly enumerate exclusions or name the alternative holiday_mode_get, 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?

Beyond annotations that mark this as a write/destructive call, the description discloses a plan prerequisite (`incident_comments_enabled`) and the upload-before-comment behavior for local files. It does not contradict annotations; it adds useful operational 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 dense sentences with no wasted words; the primary action is front-loaded, and the attachment workflow and prerequisite follow logically. Every clause adds 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 a write tool with no output schema, the description covers the main action, attachment workflow, and prerequisite. It omits return-value details and any post-create side effects, but those are not essential given the schema and annotations.

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

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

With schema description coverage at only 40%, the description compensates partially: it explains that `attached_files` must be URLs from `incident_comment_upload_file` and that `attached_local_files` are local paths uploaded first. However, it leaves `incident_id`, `comment_text`, and `confirm` semantics to inference or 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 specific verb and resource ('Adds a text comment to an incident'), which clearly identifies the operation. The attachment guidance references `incident_comment_upload_file`, distinguishing this from sibling upload/update/delete 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 gives clear context for when to call this tool (creating an incident comment) and even covers the two attachment paths, but it never explicitly contrasts it with alternatives like incident_comment_update or incident_comment_delete. Usage relative to siblings is implied 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 declare destructiveHint=true and readOnlyHint=false, and the description adds meaningful behavioral context: the deletion is permanent, includes attached files, and is irreversible. This goes beyond the annotations, though it doesn't discuss error conditions or authorization beyond what the schema's confirm parameter already states.

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

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

Two sentences, no filler, with the most important information front-loaded: the tool deletes, it's permanent, and it affects files too. Every clause adds 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 simple destructive mutation with annotations covering the safety profile and no output schema, the description is sufficient. It explains the primary consequence and scope. It could mention what happens if the comment does not exist or is already deleted, but that is a minor gap for such a straightforward operation.

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

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

Schema description coverage is only 33% (only 'confirm' is described). The description itself does not explain incident_id or comment_id semantics, their relationship, or how they should be combined. Though the parameter names are fairly self-evident, the low coverage is not compensated for in 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 clearly states a specific verb and resource: 'Permanently deletes a comment along with all attached files.' This distinguishes it from sibling tools like incident_comment_update or incident_comment_create, and the scope (comment + files) is 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?

The usage context is implied by the tool name and description—an agent would correctly infer this is for deleting an incident comment. However, the description does not explicitly contrast it with related tools (e.g., incident_delete) or state any prerequisites or conditions for use.

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=true already covering the safety profile, the description adds useful behavioral context: results are in chronological order and include attached files and timestamps. It does not mention potential pagination or auth requirements, but for a read-only listing tool, the added detail is sufficient.

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 a single, front-loaded sentence with no filler. It states the core action, the ordering behavior, and the included fields, all in minimal words.

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, one-parameter list tool with readOnlyHint and no output schema, the description is largely complete: it says 'all comments,' specifies chronological order, and lists the content. It does not mention pagination, but the explicit 'all' and the tool's simplicity keep this from being a significant gap.

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

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

Schema description coverage is 0%, so the description must compensate for incident_id. It provides context by stating the tool lists 'all comments on an incident,' making it clear that incident_id identifies the incident whose comments are retrieved. The schema already documents the integer type and positivity, so this addition covers the semantic gap.

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 ('Lists') and resource ('all comments on an incident') and adds distinguishing details: 'in chronological order, including attached files and timestamps.' This clearly separates it from sibling tools like incident_comment_create/update/delete/upload_file and incident_get_events, which cover different operations.

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 (if you need comments on an incident, use this tool) but does not explicitly state when to prefer it over alternatives or any exclusions. It does not name sibling tools or mention conditions like incident_get_events for incidents vs comments, leaving the agent to infer 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?

The description adds valuable behavioral context beyond the annotations (destructiveHint=true) by specifying that providing attached_files fully replaces the previous list and deletes omitted files from storage. This is a critical destructive side effect that an agent must know. It does not contradict 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 two concise sentences with no fluff. The main purpose is front-loaded, and the key behavioral caveat about file replacement is placed immediately after. 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?

Given the tool's moderate complexity (5 params, 2 required) and no output schema, the description covers the core operation and the most important side effect. It does not mention the confirm requirement or behavior when both text and files are omitted, but the schema covers confirm, and the rest is implied. It is sufficient for correct invocation in most cases.

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 low at 20%, so the description must compensate. It does add important semantics for attached_files (full replacement and deletion), which is not in the schema. However, it does not explain comment_text usage or the confirm parameter, though confirm is documented in the schema and comment_text is self-evident. The added value is meaningful but incomplete.

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 'Edits' and the resource 'existing comment', specifying both text and attachments. It distinguishes from sibling tools like incident_comment_create (new comment) and incident_comment_delete, leaving no ambiguity about its scope.

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 on an existing comment but does not explicitly mention alternatives or when not to use it. It lacks guidance such as 'use incident_comment_upload_file first for file uploads' or 'do not use for creation'. The context is clear from the name, but the description itself provides no explicit routing.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the write nature is known. The description adds valuable behavioral context: the two-step process (upload URL request + PUT), the 5 MB size limit, and the output format (public file_url). This goes beyond annotations without 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?

Two sentences with no redundancy. The key action ('Two-step file upload') is front-loaded, and the explanation of the workflow, output, and usage is packed into a compact structure. Every word contributes.

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

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

The description explains the workflow, return value, and size limit, which are the essential elements for an agent to call the tool correctly. It does not mention the confirm parameter's behavior (write override), but that is documented in the schema and annotations. Given the tool's simplicity and existing structured metadata, this is sufficiently complete.

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 67% (confirm and local_path have descriptions, incident_id does not). The description does not add parameter-level details beyond what the schema provides, though it implicitly references local_path via 'PUTs the local file'. Given moderate schema coverage, the baseline of 3 is appropriate, and the description does not compensate for the missing incident_id documentation.

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 ('Two-step file upload') and clearly explains the workflow: requests an upload URL, PUTs the file, and returns a public file_url. It distinguishes itself from siblings like incident_comment_create/update by positioning itself as the upload step that precedes them. The size limit adds a specific constraint.

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 mentions that the returned file_url should be passed into incident_comment_create/incident_comment_update, giving clear context on when to use this tool. It does not mention when not to use it or alternatives, but the workflow guidance is sufficient for an agent to understand its role.

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 destructive and non-read-only, but the description adds substantial detail beyond that: it's irreversible, cascades to several linked artifacts, affects uptime/SLA calculations on status pages and future reports, and behaves differently for ongoing incidents. This is exactly the kind of behavioral context an agent needs before making a destructive call.

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

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

Four sentences, each carrying unique information: deletion scope, irreversibility/confirmation, impact on uptime/SLA, and the closed-only constraint with the 409/ re-open behavior. Nothing is redundant, and the most critical facts (permanence, user confirmation) are positioned early. The length is justified by the severity of the operation.

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 nearly everything an agent needs: what is deleted, the irreversible nature, the effect on computed metrics, and the precondition on incident state. The confirm parameter's purpose is already covered in the schema, and no other major behavioral aspect is left unexplained.

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 50%: 'id' has no description in the schema, while 'confirm' is well described. The tool description does not explicitly explain 'id' or 'confirm', but it does add a meaningful constraint on what id must represent (a closed incident) and the 409 failure mode. Since id is self-evident and confirm is already documented in the schema, the marginal added value is moderate, neither great nor missing.

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-resource pair ('Permanently deletes an incident') and goes further by enumerating exactly what gets deleted: network diagnostics, screenshot, comments, AI summary, and notification history. This clearly distinguishes it from read-only incident siblings like incident_get and incident_list.

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?

Explicitly states when deletion is appropriate: only closed incidents can be deleted, an ongoing one returns 409, and the user must be asked for confirmation before calling. It also provides forward-looking guidance—'wait for recovery first, otherwise the next failed check reopens it'—which tells the agent when not to invoke the tool.

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

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

Annotations already carry destructiveHint=true and readOnlyHint=false, so the safety profile is covered externally. The description adds genuinely useful behavior beyond that: idempotency ('repeated calls return the same summary'), the caching semantics ('returns the cached'), and the preconditions for the call working. No contradiction with annotations — 'Generates' is consistent with a write/destructive call authorized via the confirm parameter.

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 first front-loads the core action and output, the second adds idempotency behavior, the third states the prerequisite. No filler, no repetition of annotation content.

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-purpose tool, the definition is nearly complete: purpose, idempotency, and prerequisite are stated, while safety is covered by annotations and the confirm parameter's schema text. The main gap is the absence of an output schema and only loose return-value description ('a short human-readable explanation'), plus undefined failure behavior when network_diagnostics_enabled is false.

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 50%: the confirm parameter is already well documented in the schema, but the sole required parameter id has no schema description. The tool description implicitly ties id to the incident ('AI summary of the incident') but never explicitly names, describes, or constrains it, so it only partially compensates for the coverage gap.

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: 'Generates (or returns the cached) AI summary of the incident', and elaborates what the summary is ('a short human-readable explanation of what happened and why, based on diagnostics'). This is specific enough to distinguish it from siblings like incident_rate_ai_summary (rating the summary) and incident_get (raw incident details), even though no sibling is named.

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 context for when to call it: when a human-readable diagnostic-based explanation of an incident is needed, and it states a hard prerequisite ('Requires network_diagnostics_enabled on the plan'). However, it offers no explicit exclusion or alternative — it never says to prefer incident_get_events or incident_rate_ai_summary in other cases — so it stops short of full 5-level guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description's additions are what matter. It usefully discloses that `screenshot` and `details` are conditionally returned based on plan flags, which is non-obvious behavior. It doesn't discuss errors or rate limits, but those are less critical for a simple read-only operation.

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 one dense sentence that front-loads the main return payload and appends conditional caveats. Every clause earns its place, and no filler or redundancy is present.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so in useful detail including plan-dependent omissions. It could additionally state that `id` comes from incident_list, but for a one-parameter read-only tool the description is largely complete.

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 0%, so the description should compensate for the `id` parameter, but it never mentions it. The only saving grace is that the single required `id` parameter is self-evident from the tool name and schema property, but the description itself adds no parameter meaning.

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

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

The description says exactly what the tool does with a clear verb ('Returns') and resource ('detailed incident card'), then lists distinguishing content such as diagnostics, replay link, and screenshot. This clearly separates it from sibling tools like incident_list, incident_get_events, and incident_get_server.

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

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

The phrase 'detailed incident card' gives strong context that this is the full-detail incident reader, implicitly contrasting with incident_list and incident_get_events/incident_get_server. It does not explicitly name an alternative or provide a when-not-to-use condition, so it is clear but not maximally 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?

Beyond the readOnlyHint/openWorldHint annotations, the description reveals plan-gated availability for screenshots/diagnostics, the HTTP-monitor requirement for screenshots, the post-2026-08-09 date constraint, and a per-type `meta` shape. This substantially enriches the agent's understanding of variability and conditional behavior.

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

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

The description is long but dense and organized: one sentence for the core purpose, one for the event/meta contract, and one for conditional availability. Each clause adds operational detail an agent needs, with no filler or repetition.

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

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

With no output schema, the description goes beyond a simple return type by documenting event types, matching meta payloads, and conditional inclusion rules. It could add explicit pagination or ordering details, but chronological order is already stated and the coverage is strong for a single-id timeline endpoint.

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 defines only `id` (integer, exclusiveMinimum 0) with 0% coverage, and the description never explicitly documents this parameter. It implies the id identifies the incident through the phrase 'of an incident', but it doesn't state how to obtain or format the value, so it only partially compensates for the missing schema documentation.

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 'Returns the chronological event log of an incident', giving a specific verb and resource. It then enumerates the exact event categories (status changes, notifications, comments, screenshots, diagnostics), making it easy to distinguish from tools like incident_get or incident_comment_list.

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 frames the tool as useful 'for audits and timeline rendering', giving an agent clear when-to-use context. It doesn't name alternatives or state when not to use it, but the use case is specific enough for routing decisions.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already known. The description adds valuable behavioral context: it returns metadata plus base64-encoded file, and it discloses the 403 failure mode when `incident_report_enabled` is not on the plan. This goes beyond the annotations and helps the agent anticipate errors.

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 no filler. The core action and output format are front-loaded, then the parameter behavior, then the failure condition. 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 2-parameter read-only tool with no output schema, the description covers the key aspects: what is returned, how sections are controlled, and the 403 prerequisite. It does not describe the exact metadata fields or the base64 format details, but given the simplicity and the annotations, it is reasonably complete.

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 50%: `sections` has a description, but `id` does not. The description adds meaning by explaining that `sections` controls section composition and defaults to all on the server side. However, it does not clarify the `id` parameter beyond the schema's type, and the schema already documents the enum values for `sections`. The description partially compensates but not fully.

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 ('Downloads'), a specific resource ('PDF report for the incident'), and the output format ('metadata plus the base64-encoded file'). It clearly distinguishes this from sibling tools like incident_get or incident_get_events by focusing on the PDF report download.

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 context: it is for downloading a ready-to-attach PDF report, and it mentions the `sections` parameter controls composition. It does not explicitly name alternatives or when-not-to-use, but the sibling list makes it clear this is the only PDF download tool for incidents, so the usage context is sufficiently 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 mark readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the 'one call' convenience trait; it does not say what happens when no monitor is linked to the incident or whether the returned monitor matches the monitor_get representation. This is useful but minimal context 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?

One compact sentence of roughly thirteen words, with the 'Shortcut' qualifier front-loaded. No filler, no repetition of the schema or annotations, and 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 read-only lookup with no output schema, the description captures the essential input meaning and the result well enough to invoke correctly. It doesn't describe the monitor object's fields, but as a 'shortcut' it likely returns the same monitor representation as monitor_get, so that gap is 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?

Schema coverage is 0% and the schema only says id is a positive integer. The description's 'given incident' supplies the key semantic that id is an incident identifier, distinguishing it from a monitor ID. It stops short of explicitly stating 'id = incident ID,' but for a single parameter the meaning is recoverable.

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 ('returns the monitor linked to a given incident') and the title 'Get monitor by incident' clearly differentiates it from incident_get (which returns the incident itself) and monitor_get (which gets a monitor by its own ID). The word 'Shortcut' signals a distinct access path rather than duplicating any sibling.

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 'Shortcut' phrasing implies this is an efficient alternative to a multi-call flow, but it never names the alternative (e.g., incident_get followed by monitor_get) or states when not to use it. The intended use case is clear—have an incident, want its monitor—but the decision rule vs alternatives is left implicit.

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

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

Beyond the readOnlyHint annotation, the description discloses sort order (start time desc), retention-depth limits, and the interaction between filters and server_id. This adds meaningful behavioral context without contradicting 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 short sentences, with the core behavior front-loaded. The opening 'Lists incidents' is slightly redundant with the title, but every subsequent clause 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 no-required-param list tool, the description covers the important modes, ordering, filter restrictions, and retention limits. It does not mention pagination or output shape, but there is no output schema and complexity is low enough that this is not a major gap.

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

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

The schema already documents server_id and project_id well (67% coverage). The description reinforces the account-wide vs. monitor-specific behavior and notes filter applicability, but it does not add much detail on what the status values mean or what the returned incident list contains.

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 that the tool lists incidents and immediately clarifies the two scoping modes (account-wide vs. a single monitor). It does not explicitly name a sibling such as incident_get for single-incident retrieval, so it misses the highest bar for 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?

It gives clear guidance on how server_id changes the call and that status/project_id filters only apply to the account-wide form. However, it never says when to prefer this tool over related tools like incident_get or incident_get_events, so the alternative-selection guidance is only 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 destructiveHint=true and readOnlyHint=false, so the mutation nature is known. The description adds the ability to clear a rating with null, which is useful behavioral context. However, it doesn't disclose side effects, idempotency, or whether overwriting an existing rating is allowed.

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 core action and the special null behavior are front-loaded and clearly stated. 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 simple 3-parameter tool with no output schema, the description covers the main action and the null-clearing behavior. However, it doesn't explain what 'id' refers to (incident ID? summary ID?), and the 'confirm' parameter's write-authorization context is only in the schema, not the description. Adequate but with a notable gap.

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

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

Schema coverage is only 33% (only 'confirm' has a description). The description adds meaning for 'rating' (positive/negative/null) but not for 'id'. It partially compensates for the schema gap but leaves 'id' semantics to be inferred from the tool name and context.

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 ('Submits feedback on the AI summary') and the specific values ('positive' or 'negative'), which distinguishes it from sibling tools like incident_generate_ai_summary. It doesn't explicitly name the sibling, but the resource and action are clear enough.

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 when to use it (to rate an AI summary) and mentions clearing a rating with null, but it doesn't explicitly contrast with alternatives or state when not to use it. The context is clear but no exclusions or alternative routing are provided.

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 provide readOnlyHint and openWorldHint. The description adds non-obvious behavior beyond those flags by stating idempotency ('Repeated calls before the link is consumed are idempotent — same links are returned') and the confirmation consequence, which is valuable for an agent deciding whether to call repeatedly.

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 add distinct information: the return value and link types, the binding consequence after confirmation, and idempotency. No filler words, and the main action 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 zero-parameter tool with no output schema, the description covers the return value, the two link variants, the binding flow, and idempotency. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters and an empty input schema, so there is nothing to clarify. Per the rules, 0 params gives a baseline of 4; the description doesn't need to add parameter information.

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 states a specific verb ('Returns') and resource ('a pair of deeplinks: link_user and link_group') with clear definitions of each. It distinguishes from siblings by focusing on generating binding deeplinks, while siblings like max_linked_list or max_unlink handle listing or removing bindings.

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 context that the deeplinks are for binding MAX as a notifications channel ('After confirmation, the MAX chat/account becomes available as a notifications channel'), which implies when to use this tool. However, it does not explicitly name alternatives or exclusions (e.g., max_linked_list for existing bindings), so it stops short of full guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful behavioral context by describing the return content (status and 2FA flag) and the tool's role as a notification channel. It does not contradict annotations and discloses the operation's non-destructive nature implicitly through the read-only intent.

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 concise sentences with no filler. The primary purpose is front-loaded in the first sentence, and the second adds relevant context without redundancy. 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 straightforward, parameterless read operation, the description is complete. It specifies what is returned (MAX accounts and group chats), the included fields (status and 2FA flag), and its applicability as a notification channel. Given the absence of an output schema, the description provides sufficient expectation of the return content without overpromising.

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 is trivially 100% covered. Per the baseline for 0 parameters, a score of 4 is appropriate; the description correctly does not attempt to document nonexistent inputs. No parameter semantics are 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 clearly states the verb ('Returns') and the resource ('all MAX accounts and group chats linked to the Statuser account'), and specifies the included details (status and 'used for 2FA' flag). It differentiates itself from siblings like telegram_linked_list by naming 'MAX accounts' explicitly and from max_get_link/max_unlink because it is a listing 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 provides some usage context by noting the tool is 'Available as a notification channel in notification rules', implying it is used when configuring notifications. However, it does not explicitly state when to use this tool over alternatives (e.g., max_get_link for individual links, telegram_linked_list for Telegram) or when not to use it. The guidance is 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 declare readOnlyHint=false and destructiveHint=true, so the write/destructive nature is disclosed by structured data. The description adds a useful constraint (the account must already be linked) but does not go further to describe side effects such as the previous account no longer receiving codes or whether the change is reversible.

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 action is front-loaded, the linkage constraint is stated immediately after, and 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 setter with two parameters and an explanatory confirm schema, this is nearly complete: the agent knows what is switched, what values are valid for max_id, and how to override write restrictions. It does not describe the return value, but no output schema exists and the operation's success response is not essential 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?

With schema description coverage at 50%, the undocumented max_id parameter is the main ambiguity, and the description helps by stating it must be one of the accounts already linked to Statuser. The confirm parameter is already fully explained in the schema, so the remaining parameter semantics are sufficiently covered.

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 ('Switches') and names the exact resource ('which linked MAX account receives second-factor confirmation codes'), so an agent can tell this is a configuration change rather than a listing, linking, or unlinking operation. It does not explicitly name a sibling alternative, but 'already linked' makes the distinction from link/unlink tools clear enough.

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 context for when to call the tool: to change which already-linked MAX account receives 2FA codes, and only for accounts already linked to the Statuser account. It does not explicitly state 'use max_linked_list to find valid max_id values' or name when-not-to-use alternatives, 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds substantial behavioral context: notification delivery stops, notification rules exclude the account, and the 2FA role is cleared automatically. The caveat about having no other 2FA channel is exactly the kind of side-effect disclosure that helps an agent avoid unintended lockout.

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 core action is stated first, followed by behavioral consequences and a targeted warning. Every sentence earns its place, and there is no redundant restating of the tool name or title.

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

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

For a destructive unlink operation, the description covers what stops happening, what gets cleared automatically, and a practical safety recommendation. The annotations cover the destructive/write nature, and the schema covers the confirm override flag. No critical behavioral information needed to invoke the tool correctly is missing.

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

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

The schema documents confirm well but leaves max_id as a bare string with no description. The description adds only that the operation targets a MAX account, which gives some semantic context for max_id but does not explain its format or source. With 50% schema coverage, this is adequate but not strong compensation.

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: 'Unlinks a MAX account from the Statuser account.' It clearly states the action and scope, and the following sentences clarify consequences, which distinguishes it from related tools like max_linked_list, max_get_link, and max_set_2fa_account.

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 conveys when this tool is appropriate by describing the effects of unlinking: notifications stop, notification rules stop including it, and 2FA is cleared. It also provides a practical recommendation about switching the 2FA channel first. It does not explicitly name alternatives or state when not to use it, but the context is clear.

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

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

The annotations already flag the operation as non-read-only and destructive, so the description adds value by disclosing default timeout/interval/redirect behavior, paid features being off by default, and the specific 403 conditions tied to plan gates. This goes meaningfully beyond the 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?

The description is two sentences and front-loads the core action before defaults and error conditions. The long second sentence is dense but earns its place by consolidating plan-gating failure modes that would otherwise be spread across many parameters.

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 28 parameters and no output schema, the description covers the minimum required parameters, default behavior, paid-feature opt-in, and major failure conditions. It does not describe the response payload, but in the absence of an output schema that is a minor gap given how much the schema and annotations already supply.

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 high at 82%, so the schema already documents most parameters. The description reinforces that only host and protocol are required and summarizes a few defaults, but it mostly restates information already present in the input schema rather than adding substantial new meaning.

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

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

The description opens with 'Creates a new monitor,' a specific verb and resource, and follows with the required parameters and default behavior. This makes it immediately distinguishable from siblings like monitor_update, monitor_pause, and monitor_delete without needing to open their 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?

No explicit when-to-use guidance is given, and no alternative tool is named. The intended use is implied by 'Creates a new monitor,' but there is no direction such as 'use monitor_update to modify an existing monitor' or any exclusion of when creation should not be attempted.

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' destructiveHint=true, the description discloses what gets permanently destroyed: history, incidents, and alert settings, and states 'Irreversible.' This adds meaningful behavioral 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?

Two compact sentences, with the key destructive implication front-loaded, followed immediately by the safer alternative. Every sentence earns its place with no redundancy.

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 action, the description covers what is deleted, irreversibility, and the alternative path. The confirm parameter behavior is already fully specified 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?

Schema coverage is 50%: the confirm parameter is fully documented in the schema, but the id parameter has no description. The tool description implies id identifies the monitor to delete but adds no detail beyond that. It partially compensates but relies on the obvious 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 names a specific verb and resource: 'Permanently deletes a monitor with its history, incidents and alert settings.' It clearly distinguishes scope from the sibling monitor_pause, and the destructive nature is unmistakable.

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?

Explicitly states when not to use it: 'To pause checks temporarily, use monitor_pause instead.' This gives an agent a clear decision rule and names the alternative tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety and world-model profile. The description adds that the response contains configuration and status, but discloses nothing beyond that — no behavior for missing/invalid ids, no note on freshness of status, and no detail about the returned structure.

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 13-word sentence with zero filler. The primary information (returns configuration and status) is front-loaded, and nothing in the description is redundant with the schema or annotations.

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 get-by-id tool with one required parameter, no output schema, and read-only annotations, the description covers the essentials: what it returns and by what key. Minor gaps — id provenance and not-found behavior — are secondary given the tool's low complexity.

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

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

Schema has 0% description coverage, so the bare integer `id` needs semantic grounding. The phrase "by id" correctly tells the agent the parameter identifies a monitor, but it does not say where the id comes from (e.g., monitor_list) or what happens for id values that do not exist.

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?

"Returns full configuration and latest status for one monitor by id" names a specific verb, resource, and scope. It clearly differentiates from monitor_list (plural collection), and from the narrower monitor_get_checks / monitor_get_heartbeat_events / monitor_get_dns_history siblings by promising the full configuration and latest status.

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

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

No explicit when-to-use or when-not-to-use guidance is given. With many closely related siblings (monitor_list, monitor_get_checks, monitor_get_heartbeat_events, monitor_get_dns_history), the description provides no steering on when this comprehensive getter is the right choice versus the more targeted getters.

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 openWorldHint already present, the description adds useful behavior: the default time window and the inclusion of a few raw points on day-scale periods. It does not discuss pagination or exact payload shape, but annotations lower the burden.

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: the first establishes purpose, the second covers defaults and an edge case. Each sentence earns its place with no redundancy.

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

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

The description gives enough to invoke the tool: required id (contextually implied by the title), optional dates with defaults, and expected output nature for graph use. A slight gap is the lack of an explicit statement that id refers to a monitor entity, but this is inferable from the name and siblings.

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 67%, and the description reinforces the default behavior for start_date/end_date, which is genuinely useful. However, the required id property has no schema description and no added explanation in the description, leaving its referent (monitor ID) implicit.

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: it 'Returns aggregated check results for the period' and positions them for uptime/latency graphs. 'Aggregated' helps separate it from raw event/check endpoints, though it does not explicitly name any sibling.

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: use for period-based graph data, and it documents the default 24h window when start_date/end_date are omitted. It does not mention alternatives or when not to use this tool, so it stops short of explicit routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: history depth is limited by the dns_history_retention_days plan feature, and non-DNS monitors return an empty array. This goes 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?

Three sentences with no wasted words. The core behavior (returns diffs) is front-loaded, followed by the retention limit and the protocol constraint. 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 single-parameter read-only tool with annotations covering safety, the description is nearly complete. It explains the return shape (diffs per record type), the retention limit, and the empty-array case. The only minor gap is not explicitly stating that id is the monitor ID, but this is strongly implied by the tool name and sibling 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 0%, but there is only one parameter (id) with a clear name and type. The description doesn't explicitly explain that id refers to the monitor ID, but the tool name and context make this reasonably inferable. The description adds no parameter-specific detail beyond the schema, so a 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 clearly states the tool returns diffs of DNS records observed by the monitor, specifying what was added and removed per record type. It distinguishes this from other monitor tools by scoping it to DNS protocol monitors.

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 this tool: only for monitors with protocol = "dns". It also tells the agent that other monitors return an empty array, which prevents misuse. This is clear usage guidance without needing to reference siblings.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description adds behavioral details: aggregated into equal intervals, empty-array fallback for non-heartbeat monitors, and a default 24h window. It does not contradict annotations and provides useful operational 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?

Three sentences, each earning its place: the core return behavior, the applicability constraint, and the default time range. The most important information is front-loaded, with no redundant phrasing.

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 tool with three parameters and no output schema, the description covers the essential context: what it returns, when it applies, and the default period. It does not mention pagination or response format, but these are less critical given the simple parameter set and existing annotations.

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 descriptions are 0% for all parameters. The description implies start_date/end_date are optional via the 'Defaults to the last 24h' note, which adds some meaning. However, it does not specify date formats, nor does it explicitly confirm that 'id' refers to the monitor ID, leaving the agent to infer these from context.

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 ('Returns heartbeat events'), identifies the resource ('pings from an external system'), and scopes it to monitors with protocol 'heartbeat', clearly distinguishing it from other monitor tools. It is not a tautology and adds concrete details about aggregation and applicability.

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 provides a clear condition for use: only meaningful for monitors with protocol = 'heartbeat', with others returning an empty array. However, it does not name a specific alternative tool to use for non-heartbeat monitors, so the guidance is conditional but not comparative against named siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the pagination recommendation, which hints at potentially large result sets, but does not disclose return format or behavior when limit is omitted. It adds some useful context but not a rich behavioral picture.

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 zero waste. The main purpose is front-loaded, and the pagination advice is practical and directly actionable. 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 list tool with no output schema and 3 optional parameters, this description is adequate but not thorough. It tells the agent it returns monitors with status and configuration, but does not specify fields or default pagination behavior. Given the open world hint, it would benefit from more detail on result set size or default limits.

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 only 33% (only project_id has a description). The tool description compensates partially by explaining that limit and offset are pagination controls, giving them purpose. However, it does not add semantics for project_id or explain defaults/ranges beyond what the schema provides, so compensation is moderate.

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 ('Lists every monitor') and the resource ('on the account'), with scope ('with current status and configuration'). It is obviously a list operation, distinct from monitor_get, though it does not explicitly name a sibling for contrast.

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 implicit usage guidance (use this to list all monitors) and practical pagination advice ('Use limit/offset to paginate'), but it does not explicitly state when to prefer this over alternatives or provide exclusions. Usage is 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 declare destructiveHint=true, but the description adds value by clarifying that the operation does not delete configuration or history and that plan-feature gating is re-evaluated on resume. This goes beyond the binary annotation and gives the agent a more precise mental model of the tool's side effects, without contradicting 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 two concise sentences, front-loaded with the primary function and key parameters. It avoids redundancy and each sentence provides essential information, making it highly efficient for an agent to parse.

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 toggle action, the description covers the core behavior, clarifies the non-destructive nature, and notes the plan-feature gating on resume. It does not mention the confirm override mechanism (though that is documented in the schema) or error handling, but given the tool's simplicity and the presence of the schema, this is sufficient 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?

With schema coverage at 33% (only the confirm parameter has a description), the description partially compensates by explaining the action parameter's allowed values and the overall purpose. However, it does not explicitly describe the 'id' parameter, leaving the agent to infer it is the monitor identifier from the context. The description adds some meaning but does not fully cover all parameters.

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

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

The description clearly states the verb (pauses/resumes), the resource (checks for a monitor), and explicitly notes that it does not delete configuration or history. It also elaborates on the action parameter values and the resume behavior regarding plan-feature gating, making it distinct from siblings like monitor_delete or monitor_update.

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 conveys clear context for when to use the tool (to pause or resume checks) and implies it is not for configuration changes or deletion. However, it does not explicitly name alternative tools or state 'use monitor_update for configuration changes' or 'use monitor_delete to remove a monitor,' so it falls short of fully explicit routing.

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

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

Annotations already flag this as a destructive write (readOnlyHint=false, destructiveHint=true), lowering the bar. The description adds the useful detail that it sends through all channels rather than a single one, but does not disclose the real-world side effects or that the call requires the confirm override, leaving the schema to carry that load.

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 the primary behavior first and the purpose second. Every clause adds information; there is no repetition of the title or 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?

The description is mostly adequate for a low-complexity fire-and-forget test tool, and the annotations/schema cover the destructive aspect. But the missing id semantics and the lack of any mention of the confirm requirement mean an agent must rely on inference or the schema alone 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 coverage is only 50%: confirm is described in the schema, but id has no description and the tool description adds no semantic meaning for it. For an integer id that is the sole required parameter, the description should state that it selects the monitor to test.

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 action ('Fires a test notification') and precisely scopes it to all channels configured for the account, including notification-rule channels and matching webhooks. This clearly distinguishes it from single-channel tools like webhook_test.

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 closing sentence gives an explicit purpose: verifying delivery without waiting for a real incident. It does not name sibling alternatives or state when not to use the tool, but the context is clear.

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

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

Annotations already mark the tool as destructive and not read-only, so there is no contradiction. The description adds useful behavioral context by specifying PATCH-style semantics and warning that creation-time plan constraints still apply, though it does not enumerate side effects like project moves or confirm requirements—those live in the 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 sentences with no filler. The most important fact—partial update—is front-loaded, and the second sentence earns its place by pointing to plan-feature constraints.

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 29-parameter destructive tool, the rich schema and annotations carry a large share of the burden, and the description covers the update model and routes to monitor_create for plan constraints. No output schema exists, but the payload shape is not essential for invoking 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?

With 79% schema coverage, most parameter documentation is already in the schema. The description adds the critical update-model rule that omitted fields are left unchanged and that plan constraints carry over, which is meaningful semantics beyond individual 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?

The description opens with 'Partial update', naming both the verb and the resource while adding the key semantic that this tool patches rather than replaces a monitor. This distinguishes it from sibling tools like monitor_create and monitor_pause rather than merely restating the title.

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 invocation guidance: pass only the fields you want to change. The reference to monitor_create also signals where plan-feature constraints live, but it stops short of explicitly stating 'use this when the monitor already exists and monitor_create when it does not'.

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 important behaviors beyond the annotations: it sends a confirmation code immediately, requires confirmation before effectiveness, and returns specific error codes (409, 429, 403). Annotations already indicate readOnlyHint=false and destructiveHint=true, and the description is consistent with these. It adds valuable operational context without contradicting the structured metadata.

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 concise (3 sentences) and front-loaded with the primary action and side effect. It efficiently includes error codes and the confirmation dependency. No filler words or redundant information, though it could be slightly more structured with a note on parameters.

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 moderate complexity (2 parameters, no output schema), the description provides essential operational details: the confirmation requirement, error codes, and the trigger of sending a code. It does not mention the success response format, but that is often implicit. It is sufficiently complete for an agent 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?

The schema has 2 parameters, with only the 'confirm' parameter having a description (50% coverage). The tool description does not add any parameter-specific details; it does not explain the 'email' parameter beyond the schema's format, nor does it clarify the purpose of 'confirm' beyond what is already in the schema. Since schema coverage is only 50%, the description should compensate but does not.

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 ('Adds a new email address') and the immediate side effect ('sends a confirmation code'). It distinguishes this from sibling tools like notification_email_confirm, notification_email_resend, and notification_email_remove by focusing on the add operation and the subsequent confirmation 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?

The description explains the flow: the address becomes effective only after confirmation via notification_email_confirm, implying you should use this tool first and then the confirm tool. It also hints at when to use alternatives via error codes (429 if a code was just sent suggests waiting or using resend, 409 if already confirmed suggests using confirm or list). However, it does not explicitly name alternatives or state exclusions, 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 mark this as non-read-only and destructive, so the bar for disclosure is lower. The description adds valuable side-effect detail: wrong/expired/exhausted codes return 403, the code is invalidated, and a fresh code must be requested.

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 core action and failure behavior are front-loaded. The routing to resend is concise and purposeful.

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 confirmation call, the description plus annotations/schema are mostly sufficient, but the id parameter's origin and the success response are not addressed. The workflow context is also thin—an agent may not know id comes from an earlier add/list/resend step.

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 only 33%, and the description does not explain the id parameter at all; it only clarifies that code is the emailed confirmation code. The confirm guard is documented in the schema, so the description adds little beyond schema for two of the three parameters.

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

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

The description names a specific operation—verifying an emailed code and marking an address confirmed—and distinguishes it from the sibling resend tool by stating that a failed confirmation requires requesting a new code. This makes the tool's role clear without needing to open the schema.

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

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

It gives the when-to-use context: after receiving a code by email and needing to confirm the address. It also explicitly provides the fallback for failed attempts by directing to notification_email_resend, which is the key alternative among email-related siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context: it explains that unconfirmed addresses are shown for UX but not used by notification rules, which is a meaningful behavioral trait beyond what annotations provide. It doesn't describe pagination or response format, but for a zero-parameter list tool this is acceptable.

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 wasted words. The first sentence states the core function and the second adds the key behavioral nuance about confirmed vs unconfirmed addresses. Information is front-loaded and 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 zero-parameter, read-only list tool with no output schema, the description is complete enough. It explains what the tool returns (emails with confirmation status) and the practical implication of confirmation. It doesn't mention pagination or ordering, but these are minor gaps for a simple list operation. The sibling context shows this is one of many notification tools, and the description sufficiently distinguishes 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?

The tool has zero parameters, so there is no parameter semantics burden on the description. The schema coverage is 100% (vacuously, since there are no properties). The description adds meaning about what the returned data represents (emails with confirmation status), which is the closest analog to parameter semantics for a parameterless tool.

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

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

The description clearly states the tool lists every email address added to the account for notifications, and it explicitly mentions confirmation status. It distinguishes itself from related notification tools like notification_email_add, notification_email_confirm, notification_email_resend, and notification_email_remove by focusing on listing.

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 clear context that this is a read-only listing tool for notification emails, and it explains the significance of confirmed vs unconfirmed addresses. It doesn't explicitly name alternatives, but the sibling list makes it obvious that this is the list operation among email management tools. The context about confirmed addresses being the only ones used by notification rules gives practical 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 mark the tool as destructive and not read-only. The description adds crucial behavioral context beyond that: it is irreversible, and reusing the same address requires a fresh add-and-confirm cycle. It also explains the downstream effect on rules. This is valuable disclosure that goes 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 two sentences, front-loaded with the primary action, and each sentence earns its place. It avoids redundancy and fluff, making it easy for an agent 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 simple two-parameter destructive tool, the description covers the essential context: purpose, effect on rules, and irreversibility. It does not explain the id parameter or mention when the confirm flag is needed, but those are partly covered by the schema. Given the tool's simplicity, the description is reasonably complete, though it could be improved by tying the id parameter to the email address.

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 only 50% — the 'id' parameter has no description in the schema, and the tool description does not clarify what 'id' refers to (likely the identifier of the email address entry). The 'confirm' parameter is described in the schema, but the description adds nothing about it. With half the parameters undocumented and no compensation in the description, parameter semantics are weak.

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: 'Removes an email address from the notification recipients list.' It clearly distinguishes this from sibling tools like notification_email_add, notification_email_confirm, and notification_email_resend by focusing on removal. The effect on rules is also stated, leaving no ambiguity about what the tool does.

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 when to use it (to stop delivery to an address) but does not explicitly mention alternatives or exclusions. It doesn't say 'use this when you want to permanently remove an email' or contrast with temporary disabling or other notification tools. The context of sibling tools makes the purpose clear, but explicit routing guidance is absent.

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

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

Annotations already mark the operation as destructive (destructiveHint=true) and not read-only. The description adds error response codes (409, 429) and the cooldown behavior, which are valuable beyond the annotations. It doesn't mention success response or other side effects, but the error disclosures are useful.

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 zero fluff. The primary action is front-loaded, and error conditions are stated compactly. 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 resend action with annotations covering safety, the description covers behavior and error states. However, it fails to explain the meaning of the required 'id' parameter, which is critical for correct invocation. Without that, the description is incomplete 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?

Schema description coverage is 50% (only 'confirm' is described). The tool description adds no parameter details; it doesn't explain what 'id' refers to. Since the description is the main source for parameter meaning and it omits 'id', the agent is left guessing. This is a significant gap.

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 ('Resends the confirmation letter') and the target condition ('to an unconfirmed email'), distinguishing it from siblings like notification_email_confirm (which likely confirms) and notification_email_add (which adds). It also includes error codes that clarify the scope.

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 (unconfirmed email) and when not to (already confirmed → 409, too often → 429 with cooldown). It doesn't name alternative tools, but the conditions are clear enough for an agent to decide. This is strong guidance but lacks explicit alternative routing.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real context beyond that: account-level types default to off for work chats because those chats are usually shared with teams or clients, and webhook subscriptions are excluded from this view. That is useful disclosure about what the returned data will and won't contain.

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?

Dense but front-loaded: the return shape comes first, then scope semantics, then the project_id fallback. The subscription types are enumerated twice (as a list and again split into monitoring types), which is mild redundancy, but each sentence carries genuine information about defaults and scoping.

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, and the description compensates fully by spelling out the returned structure (per-type boolean channel flags, per-rule scope) and the project-vs-account split. An agent knows exactly what comes back and how to interpret it without any structured return definition.

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

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

Schema coverage is 100% and the schema description already explains the omitted-project_id fallback and the exclusiveMinimum constraint. The description's sentence about the oldest project largely restates the schema, so with a single well-documented parameter the baseline of 3 is appropriate rather than exceptional.

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?

Specific verb ('Returns') plus a precisely bounded resource: the matrix of notification rules across named subscription types and channel flags. It also names the sibling concept it excludes (webhooks have their own per-webhook subscriptions and do not appear here), so an agent can separate it from webhook_list and notification_rule_set.

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

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

Gives clear operational context for the single decision an agent must make: omit project_id and the monitoring half is read from the oldest project, so pass it explicitly when the account has multiple projects, pointing to project_list. It does not explicitly route the agent to notification_rule_set for writes, but the read/write split is unambiguous from the verb.

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=false, destructiveHint=true and openWorldHint=true, so safety is covered. The description goes beyond them by disclosing partial-update semantics ('a work-chat flag that is not passed stays as it is'), the scoping side effect on the oldest project, and the return payload ('full updated list of rules'). It does not mention that the call may need the `confirm` override, though the schema documents that parameter.

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

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

It is a single dense paragraph, but it is front-loaded with the core action and every clause carries information (partial update, granularity limit, scoping, return value). The em-dash-heavy phrasing is slightly hard to scan but not wasteful.

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 11-parameter mutation tool with no output schema, the description covers the write semantics, the channel granularity limit, project vs account scoping, and the return shape. The only notable gap is the authorization/`confirm` path, which the schema documents but the description leaves unaddressed.

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

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

Schema description coverage is only 18%, so the description must carry the load, and it largely does: it groups the channel booleans, splits the `type` enum into monitoring vs account-level categories, and explains the `project_id` default and its pitfall. It omits any mention of `confirm`, and does not enumerate the enum values, but adds real 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 states a precise verb+resource ('creates or updates the rule for a single subscription type') and immediately enumerates the toggleable channels, so an agent knows exactly what is being written. It also distinguishes itself from the adjacent `notification_rule_list` (this returns the full updated list) and from `project_channel_set` (which picks the actual addresses/chats).

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

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

It names the alternative (`project_channel_set`) and the condition that selects it: this tool only toggles channels on/off, and cannot select individual recipients. It also gives the decision rule for `project_id` (monitoring types apply to ONE project, oldest by default; account types ignore it), which is exactly the guidance an agent needs before calling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the 'No authentication required' detail, which is genuinely useful behavioral context beyond the annotations. However, it doesn't disclose return format, pagination, or whether the catalog is cached/static, which would add further value.

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, zero filler. The core action and resource are front-loaded, and the authentication note is a single short second sentence. 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 zero-parameter, read-only, public tool, the description is nearly complete. The only minor gap is that it doesn't describe the exact response shape (e.g., array of plan objects), but with no output schema and a simple catalog concept, the description's mention of 'prices, limits and features' is sufficient for an agent to know what to expect.

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 there is no parameter semantics burden. The description's mention of 'prices, limits and features' gives the agent a sense of what the response will contain, which is the closest analog to parameter semantics for a no-arg tool. Baseline 4 for 0 params 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 ('Returns'), a specific resource ('public Statuser plan catalog'), and the content scope ('prices, limits and features'). It clearly distinguishes this from sibling tools like current_plan_get (which would return the caller's own plan) and project_list/monitor_list (which list user resources).

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

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

The description explicitly states 'No authentication required', which is a clear usage condition. It doesn't explicitly name alternatives or exclusions, but the public-catalog framing makes it clear this is for browsing available plans rather than checking the current account's plan. The sibling context (current_plan_get) reinforces this distinction.

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

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

Annotations only cover the safety profile (readOnly/openWorld), and the description adds genuinely non-obvious semantics: account-level notifications (invoices, security, API keys) reach every channel regardless of the project setting, and webhook scope lives on the subscription. This is exactly the kind of behavioral context structured fields cannot convey.

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

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

Front-loaded with the core action in the first clause, and the remaining content is substantive rather than filler. It is dense with em-dashes and parentheticals, which slightly hurts scannability, but 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 no output schema, the description covers what is returned (channels plus per-project usage) and the surrounding semantics. It could say more about the response shape (e.g. the enable/disable flag field) but 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?

Schema description coverage is 0% for the single required parameter, and the description never mentions project_id or its meaning. The name is self-explanatory, so the gap is mild, but the description adds nothing beyond the schema here.

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

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

States a specific verb and resource ('Lists the notification channels of the account') and clarifies the scope is account-level channels joined with per-project enablement. It explicitly excludes webhooks and routes them to a named sibling, so an agent can distinguish it from webhook_list/webhook_update and project_channel_set.

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?

Explains the domain model that governs usage: a channel is connected once for the whole account and a project only toggles it on/off for its own notifications, plus a pointer to webhook_update for the excluded case. It stops short of stating explicit preconditions or alternatives like project_channel_set for changing the setting.

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=false and destructiveHint=true, so the safety profile is covered. The description adds useful behavior beyond the annotations: the call returns the full updated list, only monitoring notifications are affected, and turning a channel off does not disconnect it from the account. It does not mention the confirm/auth override, but that is documented in the 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?

Three tightly written sentences, front-loaded with the action and followed by key scope and side-effect constraints. No filler or repetition.

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

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

For a 5-parameter mutation tool with no output schema, the description covers the main behavioral context: mutation effect, return shape, scope, and non-destructive account-level implications. It omits the confirm override and detailed parameter semantics, but the schema covers those.

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 60%, with type, channel_id, and confirm documented in the schema. The description ties the operation to a project and a notification channel but adds no syntax or meaning for is_enabled or project_id. Baseline 3 is appropriate given partial schema coverage and minimal added parameter context.

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: turning one notification channel on/off for a project, and clarifies it returns the full updated list. It distinguishes its scope from account-level channel operations by noting it affects monitoring notifications only and does not disconnect the channel from the account.

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 (enable/disable a channel for monitoring notifications), but there is no explicit guidance on when to use this versus related siblings such as notification_rule_set or project_channel_list. The scope note is helpful but not a when-to-use/alternative directive.

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

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

The annotations already mark this as destructive and not read-only, but the description adds substantial behavioral detail: 403 on plan limits, per-account count semantics, and the critical side effect that all notification channels start disabled. This goes well beyond the annotations and prepares the agent for important consequences of the call.

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

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

The description is front-loaded with the core action, then delivers the most operationally significant side effects in a compact sequence. The explanatory sentence about why channels default off earns its place by preventing a user-visible surprise. No filler or redundancy is present.

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 no output schema, the description covers all decision-relevant context: what is created, when it fails, how limits work, and what side effects occur. The reference to project_channel_set gives the agent a clear next step for enabling notifications. Nothing critical 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?

Schema description coverage is 100%, so both parameters (name and confirm) are already documented in the input schema. The description adds no new parameter-specific semantics; it focuses on behavioral outcomes instead. This meets the baseline for high schema coverage but does not elevate it.

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

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

The description opens with the specific verb and resource: 'Creates a project.' This distinguishes it from sibling tools like project_update and project_delete, and the additional context about notification channels and plan limits clarifies what creating a project entails. An agent can immediately identify this as the create operation within the project family.

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 tool's purpose as a create operation is clear, and the description gives important context about when it is relevant: creating a new client/project, with limits on the current plan. It does not explicitly name alternatives or say 'use this instead of project_update,' but the create semantic plus references to later configuration via project_channel_set provide solid implicit usage guidance.

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

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

Annotations already flag this as destructive (destructiveHint=true), but the description goes well beyond that: it discloses 409 failure cases, the fate of notification rules/channel switches/webhooks, and that moved monitors inherit destination-project rules. This is exactly the context an agent needs before invoking an irreversible operation.

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 is front-loaded, constraints follow logically, and the irreversible consequences are stated without redundancy. The length is appropriate for the complexity of a destructive operation with cascading effects.

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