Dregs

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

Beyond the sparse annotations, the description discloses two important behaviors: overwriting same-key entries and global propagation across customers. It does not mention side effects like audit logs or return values, but the key mutational semantics are transparent enough for an agent to reason about consequences.

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

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

Two short sentences with no filler. The primary action and overwrite behavior are front-loaded, and the global-propagation detail is placed second without unnecessary elaboration.

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 four-parameter mutation tool with a complete input schema and no output schema, the description covers the essential semantics: upsert behavior and global scope implications. It could additionally clarify customer-scope visibility or return behavior, but these are not critical gaps given the schema richness.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds meaning beyond the schema by explaining behavioral implications of the scope parameter: for GLOBAL datasets, value updates take effect across all customers. This clarifies an aspect the schema enumeration alone does not convey.

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

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

The description clearly states the operation: 'Add a (key, value) entry to a dataset.' It further differentiates this from a plain insert by noting that existing entries with the same key are overwritten, which is the core distinguishing behavior relative to remove_dataset_entry and list_dataset_entries.

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 overwrite semantics imply this tool is suitable for both inserting and updating entries, but the description does not explicitly state when to use this tool versus alternatives like remove_dataset_entry or list_dataset_entries. The usage context is implied rather than explicitly routed with when/when-not guidance.

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

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

It discloses that the operation queues work rather than blocking, explains the true/false return semantics including the not-found case, and notes the 10-minute background spawner context. This supplements the idempotent and non-destructive 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 front-load the action and trigger context, then state the exact return values. There is no filler or repeated schema 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 one-parameter tool with no output schema, the description covers triggering, use case, and return values adequately. It could be more complete by pointing to get_identity_analysis for retrieving the re-scored result, since the tool itself only confirms queuing.

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

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

The schema already provides 100% coverage for the single id parameter ('Tracked identity id.'), so the baseline applies. The description adds only that the id refers to a tracked identity and that an unknown id yields false, which is return behavior rather than new parameter detail.

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 ('Queue an immediate re-scoring') and a clear resource ('an identity'), and explains why it exists: to see the effect of edits without waiting for the background spawner. This clearly separates it from read-only sibling tools like get_identity_analysis and get_identity_history.

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 states when to use it: after editing an analyzer, config, dataset, or mapping. It does not name an alternative tool or state when not to use it, so it stops short of full routing 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?

With no informative annotations, the description carries the full burden and discloses key behaviors: rule creation is scoped to the current customer, conditions are ANDed, the slug is derived from the name and is what escalation rules reference, and the call returns the created rule. It does not discuss duplicate-name behavior or failure modes, but it is substantially transparent for a create tool.

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

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

The description is information-dense and every sentence serves a purpose: precondition, condition grammar, exclusions, conjunction semantics, slug behavior, and return value. It is front-loaded with the most important usage warning before the parameter details.

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 6-parameter create tool with no output schema, the description provides enough to construct valid conditions and understand what the badge can reference. It falls just short of complete because it does not reconcile the schema-required 'badge' field in condition objects or clarify the role of 'seconds' in non-IDENTITY_AGE_GT conditions.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real value by enumerating condition/category enums, the threshold range, and the meaning of IDENTITY_AGE_GT seconds. However, it lists the condition object as {condition, category, threshold, seconds} while the schema requires a 'badge' property, so the description is not fully aligned with the schema.

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

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

The description states a specific action and resource ('Create a badge rule for the current customer') and elaborates what a badge rule is with condition types and semantics. It also differentiates from the closest sibling create_escalation_rule by explicitly excluding BADGE_EXISTS and IDENTITY_AGE_LT and routing those to escalation rules.

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 opens with an explicit precondition: 'Describe the rule and confirm with the user before calling.' It also provides when-not-to-use guidance by naming the unsupported condition types and saying 'use an escalation rule for those,' which tells the agent exactly when to choose a sibling 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 are sparse (readOnlyHint, destructiveHint, idempotentHint all false), so the description carries the behavioral burden. It explains that all conditions must hold for a match, that escalations always appear in the dashboard even without channels, and that the call returns the created rule. The reference to preview_escalation_rule implies the side effect of opening escalations against identities, adding meaningful 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?

The description front-loads the purpose and the mandatory confirmation step, then expands into condition semantics and channel behavior. It is long but every sentence adds necessary information for the complex condition object; there is no fluff 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?

With no output schema, the description states the return value ('Returns the created rule'). It also covers the condition grammar, the dashboard visibility rule, and the channel reference. The only unspecified context is the meaning of 'current customer', which is systemic, and the schema already documents effectiveAt, openAfterSeconds, and closeAfterSeconds. The description is complete for a create tool of this complexity.

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

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

The schema describes properties only by type and a short label, leaving the condition object's semantics opaque. The description fully specifies the condition DSL: allowed operators (SCORE_LT, SCORE_LTE, etc.), categories, threshold range, badge slugs, and meaning of seconds for identity age. It also clarifies that channels are slugs and refers to list_channels, elevating the parameter documentation well above the schema.

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

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

The description opens with a specific verb and resource: 'Create an escalation rule for the current customer.' It distinguishes itself from siblings by using 'create' and explicitly directing the agent to preview_escalation_rule as a pre-call alternative. The 'current customer' scoping adds precision.

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

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

The description gives explicit when-to-use guidance: 'Describe the rule and confirm with the user before calling; preview_escalation_rule shows how many identities it would open against today.' It also references list_channels for channel slugs, providing a clear path for required inputs. No exclusions are needed because the tool name and create nature already separate it from update/delete/get.

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 read-only, idempotent, and non-destructive behavior. The description adds temporal-window scoping and aggregated activity semantics, but it does not describe return format, ordering, pagination, or limits. With annotations covering the safety profile, this is adequate but not rich.

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

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

Two concise sentences: the first states the technical scope precisely, and the second explains the business value. There is no filler or redundant restating of the title.

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

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

For a read-only tool with two optional parameters and strong annotations, the description is complete enough to select and invoke correctly. However, with no output schema, a bit more detail about response shape or ordering would make it fully self-sufficient.

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

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

The input schema documents both `from` and `to` parameters with date-time formats and defaults, giving 100% coverage. The description adds only the general notion of a 'given window' and no parameter-specific detail beyond the schema.

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

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

The description states a specific operation: get per-badge-rule identity groups and per-escalation-rule escalation groups with activity in a window, and interprets the result as which rules and badges are firing most. This clearly distinguishes it from sibling tools like dashboard_stats or escalation_summary.

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

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

It gives a clear use context: 'the fastest way to see what the customer's analyzers are surfacing.' However, it does not explicitly mention alternatives or when not to use this tool, so it stops short of 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 declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds an interpretive hint about bimodal/skewed distributions but does not disclose additional behavioral traits such as rate limits or response format, which is acceptable given the simple read-only nature.

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

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

Two sentences, front-loaded with the action and resource, and the second sentence offers an actionable diagnostic tip. No filler or repetition; 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?

The tool is simple (2 optional params, no output schema), and the description covers what it returns (a histogram across four categories) and how to interpret it. Annotations carry the safety profile, and the schema documents the parameters, so nothing critical is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the two optional date parameters are fully documented in the schema. The description only refers to 'the given window' without adding semantics like timezone handling or precision, so it stays at the baseline for full 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 states a specific verb ('Get'), a concrete resource ('histogram of identity scores across all four categories'), and enumerates the categories, making it unambiguous. It is clearly distinct from sibling tools like dashboard_stats (general stats) or analyze_identity (individual identity analysis), so an agent can select it without opening schemas.

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

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

The description implies when to use it: to inspect the score distribution for a window, and specifically to identify analyzers needing tuning via the bimodal/skewed cue. It does not mention alternatives or exclusions, but the context is clear enough for a straightforward read-only 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, idempotentHint=true, and destructiveHint=false. The description adds useful behavior beyond those: the window default of the last 7 days, the scope of 'current customer', and the type of aggregated metrics returned. No contradiction with annotations exists.

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

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

Two sentences with no wasted words. The first sentence states the action and scope; the second tells the agent why and when to use it. The most decision-relevant information is front-loaded.

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

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

For a simple two-optional-parameter, read-only tool, the description covers everything needed: what it returns, the default window, and its role as an entry point. There is no output schema, so listing the metric categories partially compensates, though a bit more detail on output shape would make it fully 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 coverage is 100%, so both from and to are already well documented with defaults and ISO-8601 format. The description adds a slight clarification by summarizing the window default as 'last 7 days', but the schema already carries the semantic load, so this is a solid baseline-3 score.

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 ('Get summary statistics for the current customer') and enumerates the returned contents: total identities, in-range events, and per-category averages. It also distinguishes itself as the 'entry point' for a customer review, separating it from more specialized dashboard siblings like dashboard_score_distribution and dashboard_rule_activity.

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: use it as the entry point for a customer review to get a quick health read. It does not explicitly name alternatives or state when not to use it, so it falls just short of a 5, but the intended calling context is unmistakable.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the basic destruction profile. The description adds valuable non-obvious side effects: 'stop applying its badge' and 'escalation rules that reference the badge will no longer match', plus the requirement to confirm with the user. This goes beyond the structured data.

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 first states the core action and immediate effect, the second adds the user-confirmation requirement and a critical consequence. Every sentence earns its place, and the 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 one-parameter delete tool, the description explains the effect (stops applying badge, escalation rules stop matching) and the necessary user confirmation. It doesn't discuss return values, but the annotations cover idempotency and destructiveness, so an agent has enough to invoke it correctly.

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

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

Schema description coverage is 100%, with the 'id' parameter already described as 'Badge rule id.' The description does not add further parameter-level detail, so the baseline score of 3 applies; it doesn't harm but also doesn't enrich 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 uses a specific verb and resource: 'Delete a badge rule', which clearly distinguishes it from siblings like update_badge_rule, create_badge_rule, and delete_escalation_rule. The added clause 'stop applying its badge' further clarifies the concrete effect, 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 gives strong contextual guidance: it instructs the agent to confirm with the user first and warns that escalation rules referencing the badge will no longer match. It doesn't explicitly mention alternative tools or when-not-to-use conditions, but the context is sufficiently clear for an agent to decide 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?

Annotations already mark the tool destructiveHint=true, and the description adds significant behavioral context: existing escalations opened by the rule remain but are marked as belonging to a deleted rule, and the deletion cannot be undone from the API. This goes well beyond what annotations alone 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?

Three short sentences each earn their place: the action, the side effect on existing escalations, and the confirmation requirement plus irreversibility. The most important behavioral consequence is front-loaded near the top.

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 tool with only one required integer parameter and no output schema, the description is complete. It states the action, the lingering effect on escalations, the user-confirmation requirement, and the irreversibility, giving an agent everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, with the single id parameter clearly described as 'Escalation rule id.' The description adds no additional parameter-level meaning, so the baseline of 3 applies because the schema already carries the semantic weight.

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 'Delete an escalation rule,' a specific verb and resource that is unambiguous. It is clearly distinguishable from sibling tools like create_escalation_rule, update_escalation_rule, get_escalation_rule, and list_escalation_rules.

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 a clear operational context: the tool is for deleting a rule, and it explicitly instructs the agent to 'Confirm with the user first.' It does not name an alternative tool or state when not to use it, but the precondition and the destructive nature make usage conditions clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, covering the mutation and idempotency aspects. The description adds value by disclosing the return values (true on success, false if not found), which is beyond the annotations. It does not contradict any annotations and provides useful behavior 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?

The description is a single concise sentence that packs the action, the key parameter reference, and the return behavior. No redundant words or filler. It is front-loaded with the primary purpose 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?

The tool is simple with only two parameters, no nested objects, and no output schema. The description covers the core behavior and return values. It does not mention error conditions beyond 'not found', but that is acceptable given the tool's simplicity. The annotations cover destructive and idempotent behavior, and the schema documents parameters. Overall, the agent has enough information to call this tool correctly.

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

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

Schema description coverage is 100% for both parameters (id and scope), so the schema already fully documents their meanings. The description only mentions 'by id', which adds no new semantic detail beyond what the schema provides. The scope parameter is not elaborated in the description, but the schema covers it. Baseline of 3 is appropriate given full 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 states a specific verb ('Delete') and resource ('mapping'), and clearly identifies the operation as removal by ID. It distinguishes from siblings like set_mapping (create/update) and list_mappings (read-only) through the explicit delete action. The return behavior is also noted, making the purpose unambiguous.

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

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

The description clearly implies when to use this tool: when a mapping needs to be removed. It does not explicitly mention alternatives or exclusions, but the verb 'delete' makes the use case self-evident. No guidance is given for edge cases like when to prefer set_mapping over delete, but the context is sufficient for an agent to infer the intended usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds behavioral context beyond that: it returns counts grouped by three specific statuses (not raw escalation data or a single total), and frames the operation as lightweight ('quick read'). This meaningfully clarifies what the agent should expect.

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 tightly written sentences. The first states the operation and its dimensions; the second adds a brief purpose with no redundancy. The action verb is front-loaded, 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 zero-parameter aggregation tool, the description is complete. It states what is counted (escalations), the scope (current customer), the grouping (statuses), and the intended use. No output schema is present, but the expected return shape (counts per status) is obvious from the description, and annotations cover safety and idempotency.

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 correctly identifies the scope ('current customer's') without inventing parameters, and no additional parameter explanation is needed or possible.

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 ('Count') and a specific resource ('current customer's escalations'), and further specifies the grouping dimension (status categories open, acknowledged, closed). This distinguishes it from sibling tools like list_escalations (which would list individual escalations) and get_escalation (single record). The added purpose note ('quick read on how much triage is waiting') reinforces what the tool is for, fully separating it from mere 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 gives clear context for when to use the tool: it is a summary/aggregation for a quick triage assessment, not a detailed list or a single-escalation view. However, it does not explicitly name alternative tools (e.g., list_escalations) or state when not to use it, stopping short of a full when/when-not comparison.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond annotations by enumerating what data the summary includes and noting that exceeding the monthly event limit pauses ingestion.

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 that leads with the main purpose and then lists the included information. The length is justified by the richness of the summary, though it could be broken into a list for easier scanning.

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 must explain the return value. It does so comprehensively, covering the customer, user, roles, billing plan, limits, subscription status, dates, current usage, exceeded flag, and dashboardUrl. This is sufficient for an agent to know what to expect from the call.

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

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

The input schema has zero parameters, so the schema itself is trivially complete and no parameter documentation is needed. The baseline of 4 applies; the description adds nothing about parameters because none 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?

The description uses an explicit verb ('Describe') tied to a specific resource ('the account this connection acts in') and enumerates the contained fields (customer, user, roles, billing plan, limits, usage). This clearly differentiates it from sibling get_* tools that target channels, identities, or rules.

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 does not explicitly state when to use this tool versus any alternative, nor does it name exclusions. The usage is implied by the resource it describes—an account-level summary—and there are no comparable siblings, but the guidance is left to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as error handling, response format, or side effects. Given the annotations, the bar is lower, and the description meets the minimum but does not enrich beyond the basic 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?

A single, concise sentence with no redundancy. The core information (verb, resource, scope) is front-loaded and every word is necessary.

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

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

For a simple single-parameter getter with annotations covering safety, the description is sufficient. It lacks details on return format or not-found behavior, but given the low complexity and the presence of sibling tools, it is complete enough for an agent to call correctly. Minor gap is the absence of error handling notes, which are not critical here.

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 describes the id parameter fully ('Badge rule id') with 100% coverage. The description adds no additional meaning about the parameter beyond what the schema provides. Baseline of 3 applies due to 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 'Fetch a single badge rule by id' clearly states a specific verb (fetch), resource (badge rule), and the distinguishing scope (single, by id). This differentiates it from list_badge_rules, which would return multiple rules. No 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?

The description implies the tool is for retrieving a single badge rule when an id is available, but it does not explicitly mention alternatives like list_badge_rules for multiple rules or create/update/delete for mutations. The guidance is implied through the singular scope and id parameter, but lacks explicit when-to-use vs. when-not-to-use 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds a useful behavioral trait beyond annotations: 'Secrets are never returned.' This tells the agent that sensitive data is excluded from the response, which is valuable context not available in the structured fields.

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

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

The description is two short sentences with zero wasted words. The core action and the important caveat are front-loaded. 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 fetch-by-id tool with one parameter and annotations covering read-only and idempotent behavior, the description is adequate. It states the action and the secret caveat. It doesn't detail return format or error handling, but those are not critical for a straightforward fetch operation. It is complete enough for an agent to call 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 documents the 'id' parameter with a description ('Channel id.') and coverage is 100%. The tool description does not add any additional meaning about the parameter, so the baseline score of 3 is appropriate per the rubric.

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 ('Fetch'), a specific resource ('a single notification channel'), and the identifier ('by id'). It clearly distinguishes from siblings like list_channels, which lists multiple channels, and test_channel, which performs a different 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 implies usage: when you have a specific channel id and need a single channel. However, it does not explicitly mention when not to use it or name alternatives. The purpose is clear enough that an agent can infer the correct use case without further 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, idempotentHint, and destructiveHint false, so safety is covered. The description adds useful context about included fields (geo/ASN, timestamps, flags), but does not describe response format, error behavior, or pagination, which the agent might need to know.

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

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

One tight sentence front-loads the core action and identifier, then packs meaningful return-field detail without fluff. Every phrase 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 single-fetch tool with one fully-documented parameter and annotations covering safety/idempotence, the description is sufficient: it names the resource, the key, and the returned data fields. No output schema exists, so listing the payload contents closes the main gap.

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

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

Schema coverage is 100% and the schema already describes fingerprint as the device fingerprint. The description confirms it is the lookup key, but adds no format, source, or validation details beyond the schema, so baseline 3.

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

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

States a specific verb ('Fetch'), resource ('device'), and identifier ('by fingerprint'). Distinguishes from list_devices by being for a single device, and enumerates the fields returned, leaving no 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?

Clearly implies when to use: when you have a fingerprint and need a single device's details. Does not explicitly name alternatives or exclusion criteria, but the single-vs-plural contrast with list_devices gives adequate context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new context: the return format is 'text' and that omitting the topic yields a listing with one-line summaries. It does not discuss size limits or pagination, keeping it just short of a 5.

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

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

Front-loaded with the core action and the two modes before the longer chapter-routing guidance. Every sentence carries information, though the final routing sentence is dense and could be trimmed slightly.

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

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

No output schema exists, so the description compensates by describing both return shapes (a summarized list or a text chapter) and guiding the agent to the right chapter. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100% and the enum is fully enumerated, so the schema does the heavy lifting. The description still adds value beyond it by spelling out the omit-to-list vs provide-to-read semantics and naming which chapters matter for which tasks.

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 ('Read a chapter of the Dregs manual as text') and clearly describes the dual behavior. No sibling tool overlaps, and an agent can immediately tell this is the documentation access point.

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 distinguishes the two invocation modes ('call without a topic to list... call with a topic to get that chapter') and gives concrete when-to-use guidance mapping each chapter (SCORING, ESCALATIONS, BADGES, CHANNELS, WEBHOOKS, SERVER_SDKS) to the task that requires reading it.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior, so the bar for additional disclosure is lower. The description adds useful context by enumerating the exact snapshot contents (rule, identity, score, badge, conditions, channels, acknowledgement/closure info) and the dashboardUrl field, which the schema does 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 sentences with no filler. The primary action is front-loaded, and the second sentence adds one additional return-field detail without redundancy. Every sentence contributes useful 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 simple one-parameter read-only tool with no output schema, the description covers both the lookup key and the significant return content, including the dashboardUrl. Nothing an agent needs to invoke it correctly or interpret its result 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 single parameter 'id' is already fully described in the schema as 'Escalation id' with 100% schema description coverage. The description merely echoes that the tool fetches by id without adding new semantic detail, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Fetch'), a specific resource ('a single escalation'), and the retrieval key ('by id'), making the tool's purpose unambiguous. It also differentiates itself from siblings like list_escalations and get_escalation_rule by enumerating the escalation-specific payload.

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 'Fetch a single escalation by id' clearly implies this is the tool to use when the agent has a specific escalation id and needs that escalation's full detail. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for correct selection among the listed 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, idempotentHint=true, and destructiveHint=false, and the description's 'Fetch' is consistent with those. The description adds no behavioral detail beyond the annotations, such as error/not-found behavior or required permissions, so it is adequate but not enriching.

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 short, front-loaded sentence with no filler. Every word adds meaning: it names the action, scope, and lookup key.

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 single-resource lookup with one well-documented parameter and safety annotations, the description is sufficient to invoke the tool correctly. It does not describe the return shape or 404 behavior, but 'Fetch' strongly implies the rule is returned, and the tool's simplicity keeps this gap 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 100% and the only parameter id is described as 'Escalation rule id.' The description's 'by id' reinforces the schema but does not add semantic detail like id format, where to obtain it, or constraints. Baseline 3 is appropriate because the schema carries the 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 (Fetch), a resource (escalation rule), and a lookup criterion (by id). It clearly describes the tool's function and the singular 'single' distinguishes it from list_escalation_rules, though it does not explicitly differentiate from other get_* siblings.

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

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

The intended use is implied: call this when you need one escalation rule and have its id. However, there is no explicit guidance about alternatives (e.g., use list_escalation_rules to discover ids or create/update/delete for mutations), leaving selection partly to inference.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds genuinely new behavior: a null return when the group is absent from the tenant, truncation of long attribute values, and an explicit warning that attribute values are untrusted user-authored input. These are things an agent could not learn from the structured fields.

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

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

Front-loads the fetch purpose and usage constraint in the first clause, then uses the remainder to enumerate outputs. Efficient overall, though the long enumerated return list makes it denser than strictly necessary.

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 takes on the burden of describing return shape and does so completely: name, type, member count, first/last seen, attribute map with truncation caveat, dashboardUrl, and the null case. Nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100% and the type parameter's spelling-normalization and default are fully documented in the schema. The description only adds the gloss that id is 'the customer's own id', which is marginal beyond what the schema already provides, so the baseline 3 applies.

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

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

States a specific verb (fetch) and resource (a single group) qualified by both id and type, and enumerates what the response contains. An agent can distinguish it from list_groups purely from the 'single group by its id' framing.

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 single-group scoping implies when to use it versus list_groups, and the type parameter steers the agent to list_groups to discover valid types, but there is no explicit when/when-not statement or named alternative. Usage is inferred 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable context beyond that: attribute map values are truncated and should be treated as untrusted user-written input, results include scores and badges plus a dashboardUrl, and missing identities yield null. This helps the agent interpret the return value correctly.

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

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

Three sentences carry distinct information: the action and key, the return payload plus trust caveat, and the null behavior. There is no redundancy, and the most important caveat about untrusted truncated data 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 low-complexity, single-parameter read tool with safety annotations, the description covers invocation, expected output, and the key edge case (identity not found). Although there is no output schema, the description gives enough detail about returned fields for an agent to decide whether to call it and what to do with the result.

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

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

Schema description coverage is 100% for the single parameter, which is documented as 'Tracked identity id.' The description mostly repeats that wording rather than adding new semantics. With full schema coverage, the baseline of 3 is appropriate.

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

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

The description opens with 'Fetch a single identity by tracked identity id' – a specific verb, resource, and lookup key. It clearly differs from sibling tools like list_identities, get_identity_history, get_identity_analysis, and get_identity_links, so an agent can distinguish it without inspecting schemas.

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

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

The description gives clear context: use this when you have a tracked identity id and need a single identity, scoped to the current customer's tenant, with null when absent. It does not explicitly name alternatives or exclusion conditions, but the one-parameter schema and 'single identity' wording make the intended use obvious.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context beyond that: it returns the most recent cycle, includes every analyzer observation, and explicitly returns null if the identity has not been scored yet. 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?

Three sentences with no filler. The core action and return contents are front-loaded, the purpose is stated in the middle, and the null-return edge case is a compact final sentence. 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, the description covers what is returned, the scope ('most recent analysis cycle'), the purpose, and the not-scored edge case. No output schema exists, but the description sufficiently explains the return value shape and intent.

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 100% coverage, documenting 'id' as 'Tracked identity id.' The description references 'an identity' but does not add further semantic detail about the parameter itself beyond what the schema already provides. Baseline 3 is appropriate since the schema carries the 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 uses a specific verb and resource: 'Fetch the most recent analysis cycle for an identity' and details the returned contents. It positions itself as the 'primary tool for judging whether the analyzers are reasoning correctly,' which helps differentiate it from other get_* tools, though it does not explicitly name a sibling alternative.

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

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

The description clearly indicates when to use the tool: when you need the detailed observations behind an identity's analysis, with the note that 'the score is the summary, the observations are the evidence.' It provides clear context for selection but does not state exclusions or when a sibling tool would be preferable.

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, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds behavioral details beyond annotations: ordering (newest first) and the scope (last N analysis cycles). This adds valuable 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?

The description is two sentences with no waste. The first sentence states the core function and ordering, and the second gives a concrete use case. It 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 read-only tool with two simple parameters, the description is largely complete. It conveys the per-category score history scope and ordering. However, since there is no output schema, the description might have clarified the exact return structure (e.g., what categories include), but it is not critically missing for successful 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?

Both parameters (id, limit) are fully described in the schema (coverage 100%), so the schema already documents their meaning. The description does not add any extra parameter semantics beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 'Get' and the resource 'per-category score history for an identity' with a specific scope ('last N analysis cycles, newest first'). It also provides a use case ('spotting whether a recent analyzer change moved scores'), which distinguishes it from sibling tools like get_identity or get_identity_analysis.

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 a clear context for when to use the tool ('useful for spotting whether a recent analyzer change moved scores'), but it does not explicitly name alternative tools or provide when-not-to-use conditions. It implies usage but lacks explicit exclusions, fitting the 'clear context, no exclusions' level.

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

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

Annotations already convey readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by defining what constitutes a 'link' (shared device, IP, session, or similar name/email/behavior), which helps the agent understand the semantics of the returned relationships beyond what annotations 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?

Two crisp sentences front-load the action and resource, then immediately provide the evaluative use case. There is no filler or redundant repetition of schema information, making it highly efficient.

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 read-only tool, the description covers purpose, parameter semantics (via schema), and usage context. It does not specify the exact return format, but the description's explanation of relationship types gives enough operational insight for correct invocation, and annotations cover behavioral safety.

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% — the only parameter 'id' is described as 'Tracked identity id'. The description does not add further parameter-specific nuance, so the baseline of 3 applies because the schema already documents the parameter adequately.

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 'List' and a precise resource 'cross-identity relationships for an identity', then enumerates what those relationships are (shared device, IP, session, or name/email/behavior similarity). This clearly distinguishes the tool from siblings like get_identity or get_identity_history, which operate on a single identity or its history rather than its links to other identities.

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 states when this tool is useful: 'Essential for evaluating cross-identity (fraud-ring-style) analyzers'. This provides clear evaluative context for selection, though it does not explicitly name alternatives or state when not to use it, which would make the guidance more complete.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds meaningful context: only customer-defined rules are returned, analyzer-sourced badge types are excluded, and a dashboardUrl is included.

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

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

Two tight sentences front-load the purpose and field list. The exclusion note earns its place and the dashboardUrl detail is useful, not padding.

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

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

For a zero-param read-only listing, it covers what is returned, what is excluded, and the dashboard URL. It doesn't specify ordering or pagination, but that is a minor gap for such a scoped 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?

No parameters exist, so the empty schema is complete with 100% coverage. Baseline 4 applies because the description has no parameter details to compensate for.

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: list the current customer's badge rules. Enumerates returned attributes and explicitly distinguishes from analyzer-sourced badges, making it hard to confuse with get_badge_rule or list_escalation_rules.

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 scopes to the current customer and tells agents not to expect analyzer-sourced badges here. It doesn't name an alternative tool or state when to prefer get_badge_rule, so it falls short of full 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, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context beyond annotations by specifying return fields, statuses, ordering, and the troubleshooting scenario.

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 with no filler. The primary action and output fields are front-loaded, and the use-case sentence adds practical value without 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 read-only list tool, the description is complete: it specifies what is listed, the order, the fields returned, and when to use it. The schema covers the channel id and limit, and annotations cover side-effect safety, so nothing needed to call 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?

Schema coverage is 100%, with both id and limit already described in the input schema. The description mentions 'through a channel' but does not add meaning beyond what the schema already provides for the 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 identifies the action (List), the resource (recent deliveries through a channel), and the ordering (newest first). It also lists the specific fields returned, distinguishing it from other list tools like list_channels or list_escalations.

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

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

The description gives explicit situational guidance: 'The place to look when a webhook or Slack alert did not arrive.' This makes the intended use case clear, though it does not explicitly name alternatives or exclusion conditions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the scoping to 'current customer' and notes it returns non-secret config (implying secrets are excluded) and includes a dashboardUrl, which is behaviorally relevant. It doesn't mention pagination or sorting, but for a zero-parameter tool with annotations covering safety, this is adequate.

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 carrying weight: the first lists the returned fields, the second explains the significance of slugs, and the third adds a pointer to where channels are managed. It's front-loaded with the core listing behavior and provides essential context without 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?

Given the tool's simplicity (no params, no output schema, but a specific purpose within a larger platform), the description covers the essential information: what is returned, how to use the result (slugs for escalation rules), and where management happens. It doesn't describe the exact format of the config object or pagination, but for a list tool this is usually minor. Lacking an output schema, the field list is quite helpful.

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 schema description coverage is 100% (trivially, since there are no params). The description compensates by detailing exactly what will be returned for each channel, which helps the agent understand the output without needing an output schema. This exceeds the baseline 3 because it adds specific field names and their meaning (e.g., slugs referenced by escalation rules).

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

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

States a clear verb ('List') and resource ('notification channels'), and enumerates the returned fields (slug, name, type, config, enabled flag). It also distinguishes itself from the sibling get_channel by indicating it lists all channels for the customer, whereas get_channel likely fetches one. The mention of slugs being referenced by escalation rules adds useful domain context.

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 implicitly states when to use this tool: when you need to enumerate channels or find slugs for escalation rules. It doesn't explicitly or directly reference sibling list_channel_deliveries or get_channel, but the field list and the reference to escalation rules make the use case clear. No exclusions or alternative routing are stated, which is a minor gap.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds context about the analyzer-inspection use case and the slug/scope scoping, but it doesn't disclose additional behavioral details such as pagination behavior, error cases, or return shape beyond the basic listing 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 two short sentences with no filler. The core operation is front-loaded, and the added use-case sentence earns its place by helping the agent understand intent.

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

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

For a simple, read-only list operation with well-documented parameters and helpful safety annotations, the description plus schema is largely sufficient. It could be more complete with a note about the response shape or what happens when a slug doesn't exist, but nothing critical is missing for a correct call.

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

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

Schema description coverage is 100%, so the input schema already fully documents slug, scope, and limit. The description mentions 'by slug and scope' but adds no parameter-level meaning beyond what the schema provides, warranting the baseline score of 3.

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

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

The description uses a specific verb ('List') and a clear resource ('(key, value) entries of a given dataset'), scoped by slug and scope. This distinguishes it from sibling tools like list_datasets and add_dataset_entry/remove_dataset_entry 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?

The phrase 'Useful for inspecting what an analyzer will match against' gives a concrete use case and clear context for when to call this tool. It does not explicitly name alternatives or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context beyond annotations: it specifies that the tool returns entry counts alongside dataset names, and clarifies the semantic of 'datasets' as lookup tables for analyzers. This is useful and not contradictory.

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 with no fluff. It leads with the action and resource, then immediately clarifies scope and purpose with an example. Every sentence earns its place, and it is appropriately sized for a simple read-only list tool.

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

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

For a one-parameter, read-only list tool with full schema coverage and safety annotations, the description is complete. It explains what datasets are, what scope means, and what is returned (datasets with entry counts). No output schema exists, but the return is straightforward and sufficiently described. Nothing critical is missing.

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

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

Schema coverage is 100% and the parameter description in the schema already explains the two values ('Either CUSTOMER (the customer's overlay datasets) or GLOBAL (shared by all customers).'). The tool description reiterates this without adding new details, so it provides no value beyond the schema. 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 states a specific verb ('List') and resource ('well-known datasets') and clarifies scope (CUSTOMER or GLOBAL). It provides an example (disposable_email_domains) that illustrates what datasets are, making it distinct from siblings like list_dataset_entries. However, it does not explicitly name an alternative, so it narrowly misses a 5.

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

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

The description implies when to use this tool (when you need the list of datasets and their entry counts) but does not explicitly state when not to use it or mention alternatives. Given the sibling tools, there is a natural alternative (list_dataset_entries) but no guidance is provided to differentiate them in terms of usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds useful behavioral context: ordering by lastSeenAt by default, optional filtering by identity or free-text term, and the 'at most 100 devices' limit. These go beyond the annotations and clarify what the call returns.

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, well-structured sentence that front-loads the main purpose ('List tracked devices'), then packs in ordering, filters, and limit without wasted words. It is concise and informational 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?

Given the tool has 6 optional parameters and no output schema, the description sufficiently covers the core behavior: listing, default sort, filters, and the cap at 100. While it doesn't detail pagination mechanics (offset) or return fields, those are partially addressed in the schema and are not critical for a listing tool. Overall, an agent has enough 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 100%—every parameter has a description, so the schema already documents each field. The description synthesizes the overall behavior (e.g., 'ordered by most recently seen' and 'optionally filtered') but does not add meaning beyond what the schema provides. Per the rubric, a baseline of 3 is appropriate when schema covers 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 'List tracked devices for the current customer' with a specific verb and resource. It distinguishes this from siblings like get_device (which likely retrieves a single device) and other list_* tools by explicitly scoping to devices. It also adds default ordering and filter options, 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 explains what the tool does and some behaviors (default sort, filters, max limit) but does not explicitly advise when to use it versus alternative tools such as get_device or list_identities. There is no 'when not to use' or mention of alternatives, so an agent must infer from the general list nature that this is for multiple devices.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add context beyond that. It adds the scoping ('current customer's') and the return detail dashboardUrl, but does not mention pagination, ordering, or whether all rules are always returned. This is acceptable but not rich.

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

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

Two succinct sentences with the main verb and resource front-loaded, followed by a compact field list and one useful dashboardUrl detail. 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 zero-parameter read-only list tool, the description gives the important output fields and the dashboard URL, so an agent can understand what it returns. It is slightly incomplete because there is no output schema and no mention of response shape, pagination, or ordering, but these are minor for a settings list.

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

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

There are zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameters. Per the rubric, zero-parameter tools get a baseline of 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 uses a specific verb ('List') and a specific resource ('the current customer's escalation rules'), and enumerates the returned attributes (conditions, severity, channels, delays, enabled flag, dashboardUrl). It is clear about what the tool does, though it does not explicitly differentiate itself from the sibling list_escalations or get_escalation_rule.

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 'current customer's' scope gives context, and the list verb implies when this tool is appropriate, but the description contains no explicit guidance about when to prefer it over closely related siblings such as get_escalation_rule or list_escalations, and no exclusions are 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond this: ordering, filter precedence, the default exclusion of PENDING escalations, and the detailed structure of each returned escalation (rule, identity labels, score/badge snapshot, triggering conditions, delivery channels). This gives the agent a solid understanding of what the tool returns and how it behaves, though it does not mention pagination or the includeDeletedRules default (which is 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?

The description is only three sentences, each serving a clear purpose: state the primary function and ordering, explain filter behavior and defaults, and list the return payload fields plus the sibling alternative. Information is front-loaded (the core action appears first) and there is zero fluff or redundancy. Every sentence earns its place.

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

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

For a list tool with six optional parameters and no output schema, this description covers the essential behavior: what it lists, the order, the filter semantics, default filtering, and the shape of each returned item. It also points to escalation_summary for aggregate counts. Minor omissions like explicit pagination handling (though limit is in the schema) and a pointer to get_escalation for single records prevent a 5, but given the schema and annotations already supply parameter details and read-only behavior, the description is complete enough 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?

While the schema already documents all 6 parameters with descriptions (100% coverage), the description adds valuable parameter-interaction semantics by explaining that filters are alternatives applied in a specific order and describing the default when no filters are given. This goes beyond the individual parameter descriptions and helps the agent reason about combined usage. No parameter descriptions are repeated, so the added value is genuine.

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 ('List'), the resource ('the current customer's escalations'), and the ordering ('newest first'). It also distinguishes the tool from siblings like escalation_summary ('Use escalation_summary for counts by status') and implicitly from get_escalation and list_escalation_rules. An agent can immediately understand what this tool does and how it differs from related tools.

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

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

The description explicitly directs users to escalation_summary for counts by status, providing a clear alternative for a different need. It also explains the filter semantics ('Filters are alternatives applied in this order') and default behavior, giving context for when to use this tool. It does not explicitly mention get_escalation for single-record retrieval, but the distinction is implied by 'list' versus 'get', so this is a minor omission rather than a misleading one.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds useful behavior beyond them: default ordering by lastTrackedAt and the hard cap of 100 groups returned. It stops short of spelling out pagination, though the offset/limit schema largely covers that.

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 purpose, followed by ordering, filters, a cross-reference, and a return cap, all in three sentences with no filler. The lead sentence is long and parenthetical-heavy, which slightly taxes readability but every clause carries 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 read-only list tool with no output schema, the description supplies what an agent needs: what is listed, default ordering, filter options, the return-size cap, and the sibling to use for member details. Annotations carry the safety profile, leaving no material gap.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes a step further by tying parameters to intent: default sort is recency, the identity filter specifically lists the groups an identity belongs to, and the type filter uses the customer's own naming. That interpretation aid is value beyond the schema's field-level text.

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

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

States a specific verb and resource and immediately disambiguates what 'groups' means here (customer-reported collectives, 'not clusters Dregs detected') and what is returned (type plus member identity count). An agent can distinguish it from get_group and list_identities without opening any 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?

Gives explicit alternatives: to list a group's members, call list_identities with its id and type. It also names the available filter modes (type, free-text term, identity id) and what each is for, so the agent knows which to reach for.

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

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

Annotations already establish readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds behavior beyond that: a 100-item page cap, the fact that unknown sort values fall back to lastTrackedAt, and that offset walks the full population. It doesn't discuss rate limits or result shape, keeping it at a solid 4 rather than 5.

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, front-loaded with the resource and default ordering before filters, sorting, pagination, and the practical tip. No filler, though the second sentence packs several distinct topics (filter, sort, paginate, tip) into one long clause chain.

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 17-parameter, no-required-arg list tool with rich schema coverage and no output schema, the description covers the filter surface, ordering, and pagination model adequately. It leaves the returned identity shape and the interaction between multiple simultaneous filters unstated, which is a minor gap rather than a blocking one.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds relational meaning the schema does not state on its own — that the group filter returns members given an id and type, that offset should be a multiple of limit, and that the page cap is 100. That dependency between group and groupType is a genuinely useful clarification beyond the field-level docs.

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 ('List tracked identities'), scopes it ('for the current customer'), and declares the default ordering ('most recent activity (lastTrackedAt)'). An agent can immediately distinguish this bulk-list tool from siblings like get_identity, analyze_identity, or search_events.

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

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

Gives clear operational context: which filters are available (term, device, group, badge, score ranges), how to re-sort, how to paginate, and even a task-oriented tip (sort a score ascending or use its Max filter to surface the worst identities). It stops short of naming when NOT to use it versus list_devices/list_groups, so it's strong but not exhaustive.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful domain context about what mappings are, but it does not disclose behaviors such as ordering, pagination, or whether all mappings are returned.

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 first sentence states the action and scope; the second clarifies the domain concept and provides concrete examples.

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

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

For a simple read-only list tool with two enum-constrained parameters and full schema coverage, the description is mostly complete. It could add return-shape or scope-semantics details, but the lack of an output schema is mitigated by the straightforward 'list' semantics.

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

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

Schema description coverage is 100% for both parameters, so the schema carries the load. The description adds meaning to 'kind' by explaining IDENTITY_FIELD vs EVENT_TYPE mapping roles, but 'scope' is not elaborated beyond the schema's enum values.

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

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

The description states a specific verb ('List') and resource ('source-to-canonical mappings') and qualifies it by kind and scope. It clearly explains what mappings are, but it does not explicitly distinguish itself from sibling tools like set_mapping or delete_mapping, so it stops short of full differentiation.

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

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

The context is clear: use this tool to retrieve mappings for a given kind and scope, and the explanation of kinds indicates when each variant applies. It does not name alternatives or exclusions, but for a simple read-only list operation the intended usage is evident.

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 and idempotentHint annotations, the description adds 'without saving anything,' which reinforces the dry-run behavior. It also discloses the matching semantics ('All conditions must hold') and the output concept ('Count how many... match'), giving a complete behavioral model.

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 first states purpose, the second gives usage timing, and the rest fully specifies the condition syntax. There is no filler or repetition, and the most important facts are 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 read-only preview tool with no output schema, the description covers what it computes, when to call it, and how to structure each condition. Nothing needed 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 only describes the conditions array generically, but the description fully documents each condition object: the valid condition enum values, category values, threshold range, badge slug semantics, and seconds meaning. This far exceeds what the input schema provides.

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

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

The description opens with a specific verb and resource: 'Count how many of the customer's identities currently match a set of conditions'. It also states the operation has no persistence ('without saving anything'), which clearly distinguishes it from create_escalation_rule and update_escalation_rule.

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

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

The description explicitly names when to use the tool: 'Use it before create_escalation_rule or update_escalation_rule to show the user what a rule would open.' It gives the agent a precise decision rule and names the relevant sibling alternatives.

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

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

The annotations already communicate destructiveHint=true and idempotentHint=true, so the core behavioral profile is known to the agent. The description adds no extra context about the permanence of removal, behavior on a missing key, or any side effects, but it does not contradict the annotations either.

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, focused sentence of eight words that front-loads the core action and resource. There is no redundant wording, repetition of the title, or filler, making it an efficient definition.

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 three-parameter delete operation, the combination of a clear description, fully described parameters, and annotations covering destructiveness and idempotency is nearly sufficient. The only missing element is what happens when the key does not exist (e.g., no-op vs. error), but the idempotentHint already implies a tolerant behavior.

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

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

Schema description coverage is 100%, with clear definitions for `key`, `slug`, and `scope`. The tool description only reinforces the `key` parameter with 'by key' and does not add new meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description states a precise action ('Remove an entry from a dataset') and the mechanism ('by key'), which clearly targets the dataset-entry resource. It implicitly contrasts with the sibling `add_dataset_entry` and `list_dataset_entries`, so an agent can identify this as the deletion counterpart without inspecting other 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?

There is no guidance on when to use this tool versus alternatives such as `delete_mapping` or `add_dataset_entry`. The description does not mention prerequisites, scope constraints beyond the schema, or any caution about destructive effects, leaving usage context entirely to the agent's inference.

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

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

Beyond the annotations (which already cover readOnly/idempotent/non-destructive), the description discloses ordering (newest-first), data truncation of long values, a security warning to treat event data as untrusted user-written input, and retention-window exclusion. These are meaningful behavioral traits the structured fields do not carry.

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 tight sentences, front-loaded with the core action and scope, then filters, then output behavior and the retention caveat. Every clause carries information and nothing is repeated.

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

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

With no output schema, the description compensates by describing return ordering and truncation, and it flags the retention limit and input-trust caveat. Nothing an agent needs to call this correctly appears to be missing.

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

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

Schema description coverage is 100%, so all seven parameters are already documented in the schema, including defaults and formats. The description merely restates the filter dimensions without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Search) and resource (tracked events) scoped to the current customer, and lists the filterable dimensions. No sibling tool offers event search, so an agent can identify it uniquely without opening a 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?

The description explains that filters are optional and names the available dimensions, which implies usage, but it never states when to reach for this tool versus alternatives such as get_identity_history or list_groups, nor any exclusions or prerequisites.

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

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

The description goes well beyond the destructiveHint and idempotentHint annotations by revealing that the identity and up to 500 identities sharing its devices are re-scored, that it stops counting against other identities, and that it returns true only if the identity was found. This gives the agent a clear picture of the blast radius and outcome.

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 primary action and consequence, and the critical user-confirmation warning is placed separately. It is somewhat long, but every clause contributes necessary behavioral or side-effect 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 two-parameter mutation with no output schema, the description covers the action, the meaning, the side effects, the confirmation requirement, and the return contract. Nothing an agent needs to invoke it safely and correctly is missing.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds real semantic value by explaining what 'disregarded' means and what the boolean flag implies operationally, which is more than the schema's bare 'true to disregard, false to regard again'.

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 ('Mark an identity as disregarded'), defines the target concept precisely ('operator, tester, or other account that is not a real user'), and states the concrete effects. This makes its purpose clear and distinguishes it from read tools like get_identity or list_identities.

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 on what the tool is for and includes an explicit user-confirmation prerequisite before the operation. It does not name alternative tools or state when not to use it, but the context is strong enough for an agent to select it 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?

Annotations already flag destructive and idempotent behavior, and the description adds the critical specifics: uniqueness tuple (scope, kind, source), overwrite semantics on re-set, and null return for invalid canonical targets. This is exactly the behavioral context an agent needs 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?

Two compact sentences front-load the action and then pack the essential uniqueness, overwrite, and return-validity behavior. No filler or repetition of schema fields.

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

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

For a moderately complex upsert tool with idempotence/destructive annotations and a 100%-covered schema, the description covers scope, uniqueness, overwrite, and invalid-target return. It does not state the success return value, but that is a minor omission for a side-effecting mapping setter.

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 already documents every parameter at 100% coverage, so baseline is 3; the description adds relational meaning not in the schema by defining the uniqueness key across scope, kind, and source and the overwrite effect on target. That lifts it slightly above baseline.

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

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

Begins with a clear action ('Create or update') and resource ('a mapping at the given scope'), and the uniqueness/overwrite detail separates it from sibling list_mappings and delete_mapping. The description tells an agent exactly what the tool accomplishes.

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

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

The verb phrase 'create or update a mapping' clearly marks this as the write/upsert tool for mappings, contrasting implicitly with list_mappings (read) and delete_mapping (removal). It does not explicitly name alternatives, but the context makes the selection obvious.

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?

Even though the annotations already mark the tool as not read-only, the description adds important external side-effect context: a webhook receiver or Slack room will see a real test message. It also clarifies that true means queued or sent and instructs user confirmation, which is useful beyond the structured annotations. There is no contradiction with the annotations.

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

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

Three short sentences, each carrying distinct information: the action, the external-impact warning, and the return value. There is no filler and no repetition of the input schema.

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 tool with no output schema, the description provides enough operationally: it identifies the target, warns about external visibility, states the return value, and conveys queued/sent semantics. No critical detail appears 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 covers the sole id parameter completely with 'Channel id.' The description adds no additional meaning about the parameter format, constraints, or how the id is used beyond what the schema provides. This matches the baseline for full 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 opens with a specific verb and resource — 'Send a test notification through a channel' — and clarifies the purpose is for the user to confirm arrival. This distinguishes it from siblings like get_channel, list_channels, and list_channel_deliveries, which read or retrieve rather than send.

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 this when the user needs to confirm a channel receives messages, and it warns to confirm with the user first because a real message is sent. It does not name explicit alternatives or when-not-to-use conditions, so it stops short of a 5.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true, but the description greatly expands on these. It states partial update semantics, the exact condition object format and valid operators, restricted condition types (no BADGE_EXISTS, no IDENTITY_AGE_LT), the requirement that all conditions must hold, and that the response is 'the updated rule.' This exceeds what annotations capture and gives the agent full behavioral expectations.

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

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

The description is concise and front-loaded: it states the purpose and partial-update behavior first, then the condition format, then constraints and the return value. Every sentence serves a purpose, with no filler. It is slightly longer than minimal but the density of domain-specific information justifies the length.

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 complexity (8 params, deeply nested conditions, no output schema), the description covers everything an agent needs: how to update, what conditions are valid, what are the constraints (no badge references, no identity age LT), the confirmation requirement, and the return value. It also accounts for escalation rule alternatives. No critical information is missing, making it a self-contained guide 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 each parameter already has a description. The description adds value by explicating the 'conditions' array structure—the most complex parameter—documenting allowed condition values, categories, threshold ranges, and the meaning of seconds. For other parameters like name and type, the schema already suffices. Thus the description meaningfully supplements the schema, particularly where the schema only lists properties but lacks domain rules.

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 the action clearly: 'Update a badge rule' with a specific resource. It distinguishes itself from siblings like create_badge_rule and get_badge_rule by the verb, and adds domain-specific detail about partial updates and condition structure, 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 gives explicit guidance on when to use this tool: 'Pass only the fields to change; omitted fields keep their values' and instructs to 'Confirm with the user first.' It also directs alternatives for unsupported condition types: 'use an escalation rule for those.' However, it does not explicitly contrast with create_badge_rule or list_badge_rules, but it is clear this is for modifying an existing rule, which is implied by 'update' and 'pass only fields to change.'

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, idempotentHint=true), the description discloses meaningful behavior: the partial-update contract and the condition evaluation rule ('All conditions must hold for the rule to match'). The 'Confirm with the user first' instruction reinforces the destructive hint. No contradiction with the annotations.

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

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

The description is front-loaded with the essential update semantics before the detailed condition specification. The condition paragraph is dense but contains information available nowhere else, so every sentence earns its place. It is longer than ideal but not bloated.

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 complex 9-parameter mutation tool with no output schema, the description is thorough: it covers partial-update behavior, the full condition contract including enum values and ranges, the all-conditions-must-hold semantics, and the return value ('Returns the updated rule'). Nothing an agent needs to call it safely and correctly is missing.

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

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

Schema coverage is 100%, establishing a baseline of 3. The description adds substantial value by mapping condition types to their required fields – SCORE_* requires category (with enum values) and threshold 0-100, BADGE_* requires a badge slug, IDENTITY_AGE_* requires seconds. This dependency information exists nowhere in the schema, so the description earns an above-baseline score.

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

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

The opening line 'Update an escalation rule' is a specific verb+resource statement that clearly conveys the action. Partial-update semantics ('Pass only the fields to change; omitted fields keep their values') add real precision. It distinguishes itself from siblings implicitly by the action verb (update vs create/delete/get/preview) but never names the alternatives explicitly.

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

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

The description gives clear operational guidance: partial updates leave omitted fields unchanged, and the agent is told to 'Confirm with the user first' – appropriate for a mutation tool. However, it does not explicitly say when to prefer this tool over create_escalation_rule or preview_escalation_rule, leaving the routing to inference.

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

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

Annotations only indicate non-readOnly and non-destructive. The description adds substantial behavioral context: the recording of current user/time, the permanence of closing until a rule reopens, and the requirement to confirm with the user. This goes well 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?

Two tight sentences, front-loaded with the core action and side effects, followed by a critical caution. No fluff; 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 two-parameter mutation, the description covers all essentials: valid status changes, the need for confirmation, permanence of closure, and the return value. With full schema coverage and no output schema, nothing an agent needs to call 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 already fully describes both parameters with 100% coverage: id and status (including valid transitions). The description restates the status behavior but adds no new parameter-specific details beyond the schema, so it meets the baseline without enhancement.

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

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

The description clearly states the tool's specific actions: acknowledge an OPEN escalation or close an open/acknowledged one, and records the user and time. It distinguishes this status-update operation from sibling read/list tools by its verb and resource focus, and the action is unambiguous.

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

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

Provides clear context for when to use (for status transitions) and a critical guideline to confirm before closing. It does not explicitly name alternatives or exclusions, but the purpose is self-evident given the sibling set; the confirmation requirement is a strong usage directive.

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