Fixter

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

With no annotations provided, the description carries full behavioral burden. It discloses authorization (ADMIN only), idempotency, source overwriting, return value as JSON, and UUID semantics. It doesn't mention failure modes or permission-denied behavior, but it meaningfully covers the key behavioral traits.

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 dense and purposeful: the core action + access restriction, the edge-case behavior, and the return-value usage guidance. No filler or repetition; content is front-loaded with the most important facts.

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

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

For a 2-parameter tool with no output schema, the description is fully sufficient: it states the operation, auth requirement, idempotency, return format, and how the result should be consumed in related services. There are no significant gaps for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying channelId is a Slack channel id, explaining the no-op/overwrite semantics for channels already configured, and warning that the returned UUID is different from channelId and must be used downstream. This goes beyond the schema's field descriptions.

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

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

Uses a specific verb ('Add') with a clear resource ('Slack channel id' to 'notification-channel list'). It is immediately distinct from siblings like remove_alert_channel and list_alert_channels, and the description states the exact operation and target.

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

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

Explicitly states ADMIN-only access, idempotency semantics, the overwrite behavior when sources is provided, and cross-tool guidance that the returned UUID (not channelId) must be used in Fixter alert-rule routing. This gives clear when-to-use and how-to-integrate context beyond the schema.

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 annotations, the description fully explains behavioral nuances: by default it reads a pre-aggregated rollup for cheap wide-window queries, while the parent breakdown is computed on demand over raw spans and must be scoped. It also clarifies the returned metrics and percentage units, giving the agent a faithful model of what happens.

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 structured into clear sections: headline, usage guidance, parent-breakdown caveat, parameter list, and return shape. Every sentence adds value, and the examples are illustrative without being padded. It is appropriately detailed for a tool with six parameters and no output 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?

Given no output schema, the description fully enumerates the return fields (buckets, group, spanCount, errorRate, quantileNanos, queryStats, etc.). It also covers when to use the tool, how to scope expensive operations, and the meaning of all parameters, making the agent well-equipped to invoke it correctly.

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

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

The schema already covers the parameters at 100%, and the description goes well beyond that with concrete formats and defaults: step units, 'omit for a single window', default groupBy of 'service, operation', and the semantics of parent_operation. This adds practical meaning beyond the schema's property descriptions.

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

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

The description opens with a specific action and resource: 'Aggregate spans into RED metrics: request count, error rate, throughput, and latency percentiles...' It clearly states what the tool computes and the grouping dimension. It also distinguishes itself from sibling raw-span tools by explicitly pointing to 'spans / get_trace' for drill-down after aggregation.

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 explicit 'START HERE' guidance for common questions ('where are errors / latency concentrated?', 'what changed between two windows?', 'is this operation slow?'). It names alternatives ('Drill into raw spans (spans / get_trace)') and warns that parent breakdown is over raw spans and should be scoped with tight from/to and filters.

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?

No annotations are provided, so the description carries full burden. It discloses limits (up to 1000), window derivation rules, behavior when trace is unknown (spans/exemplars empty but logs returned), verbose flattening and string capping, and the traceUrl as shareable evidence. No contradictions exist.

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 lengthy but well-structured with clear sections (summary, return list, usage, caveats). Every sentence adds necessary information for a complex tool. Slight redundancy remains (return list repeated), but overall it is appropriately detailed without fluff; front-loaded with the core purpose.

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 no output schema, the description thoroughly covers return fields, limits, edge cases, and behavioral nuances. It explains window derivation, empty-trace handling, and provides operational guidance (e.g., large verbose responses). This is complete for an agent to use 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 covers 100% of parameters, but the description adds meaningful context beyond schema: explains verbose's effect on return structure (flattens attributes, adds resource object), how maxStringChars controls truncation, and the practical advice to prefer verbose=false first. This enhances parameter understanding beyond the schema description.

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

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

The description starts with 'One-shot cross-signal pivot for a trace id' and explains it returns trace summary, spans, logs, and exemplars for a given traceId. It clearly distinguishes itself from siblings like run_sql and logs by stating 'Use this as the primary entry point' and explicitly lists when to use alternatives.

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

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

Provides explicit when-to-use ('primary entry point when you have a trace id and want to see all correlated signals at once'), when-not-to-use ('for error triage, the logs tool ... is a cheaper, targeted alternative'), and names alternatives (run_sql for raw columns, logs, spans, metrics). It also advises on verbose=false first for long-lived traces.

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 annotations, the description discloses the scheduled/interval execution, tracking of uptime/correctness, and return of the created test with id and current state. This goes beyond a simple create by explaining ongoing behavior, though it omits potential permissions or immediate execution details.

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

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

Four sentences efficiently cover purpose, type selection, and return info. Every sentence adds something, though 'Use this to start watching' is slightly redundant with the opening sentence.

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

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

Despite having 26 parameters and no output schema, the description provides a comprehensive overview including purpose, mode selection, and return value. The detailed parameter behavior is left to the schema descriptions, which are complete. It lacks deeper details like error handling but is adequate for a complex creation tool.

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

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

Schema coverage is 100%, but the description introduces inaccurate parameter names ('httpTarget', 'mcpTarget') that don't exist in the schema (actual names are httpUrl and mcpUrl). The type-grouping advice is useful but the errors could mislead an agent into passing invalid parameters, undermining the added value.

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

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

The description clearly states the tool creates a scheduled API test for HTTP endpoints or MCP servers, with a specific verb ('Define') and resource. It distinguishes itself from sibling tools like create_api_test_credential and update_api_test by focusing on the creation of the test itself.

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

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

It explicitly instructs when to use the tool ('Use this to start watching an HTTP endpoint or an MCP server') and provides type-specific guidance (set type='HTTP' or 'MCP' with relevant params). It doesn't explicitly mention alternatives for modification, so not a full 5.

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

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

With no annotations provided, the description carries the behavioral burden and discloses the most critical trait: 'The secret is write-only: the response returns only id, name and type.' It also reveals the type-conditioned validation expectations (e.g., 'at least one entry across the two' for API_KEY). It stops short of covering duplicate-name behavior or failure modes, but the key security-relevant behavior is transparent.

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

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

Three sentences, each earning its place: purpose, type-to-field mapping, and write-only response behavior. The dense second sentence is structured with clear type labels (BASIC, BEARER, API_KEY, OAUTH2_CLIENT_CREDENTIALS) that make the conditional logic scannable despite 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 12 parameters, nested objects, no annotations, and no output schema, the description covers the essentials: purpose, conditional field requirements, response shape, and downstream usage via httpCredentialId/mcpCredentialId. Additional edge-case detail (duplicate names, limits) would be needed for a 5, but this is strong for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by synthesizing the 12 parameters into a type-driven decision matrix (BASIC: username+password, BEARER: token, etc.) and highlighting conditional rules like the at-least-one API_KEY requirement and optional scope/audience. This goes beyond what the per-field schema descriptions provide.

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

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

The description opens with a specific verb+resource: 'Store a reusable auth credential that API tests can use to reach a protected endpoint.' This clearly distinguishes the tool from siblings like create_api_test (creates the test) and delete_api_test_credential/list_api_test_credentials (lifecycle operations on existing credentials).

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 establishes clear context: credentials are stored once and reused by API tests to reach protected endpoints, and the returned id plugs into an API test's httpCredentialId or mcpCredentialId. It does not explicitly name alternatives or exclusions, but the sibling set contains no competing credential-creation tool, so the usage context is effectively unambiguous.

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

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

Despite no annotations, the description discloses critical behaviors: it is a WRITE operation requiring ADMIN role, it affects burn evaluation rather than notifications, URL_PATH values are normalized, and rules can be permanent or expire after expiresInHours. This goes beyond baseline.

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

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

The description is front-loaded with core purpose and key distinction, then uses clear sections (Scope, Duration) for parameter details. Each sentence provides necessary information with no fluff, making it well-organized for an agent to parse.

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

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

With six parameters, no annotations, and no output schema, the description fully compensates by covering admin requirements, signal constraints, edge cases, and expiration behavior. It leaves no major gaps for correct invocation.

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

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

The schema already covers all parameters, but the description enriches semantics by explaining why operation is required for LATENCY_P95, what THROUGHPUT implies, how URL_PATH normalization works, and what omitting expiresInHours means. These details are not present in the schema and materially improve correct usage.

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 defines the tool as creating ignore rules that exclude traffic fingerprints from burn-rate alert evaluation, using specific verbs and resources. It distinguishes itself from suppress_signal (which mutes notifications) and from listing/deleting rules, making its 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?

Provides explicit when-to-use guidance: 'To temporarily silence alert notifications without changing evaluation, use suppress_signal instead.' Also explains parameter requirements such as operation being required for LATENCY_P95 and THROUGHPUT having no burn evaluation, helping the agent choose appropriate values.

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

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

The description discloses that deletion is permanent and that any authenticated user can perform it. However, it does not mention idempotency, error behavior, or consequences beyond permanence. With no annotations, this is moderate disclosure.

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 segments with no wasted words. The 'WRITE' prefix efficiently flags operation type while the main sentence states the action.

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 covers the action, permanence, and access. It omits return value or error handling, but given simplicity and no output schema, it is reasonably complete.

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

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

Input schema covers ruleId with type and description, and the description adds no extra parameter detail beyond referencing 'alert rule.' Schema coverage is 100%, so 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?

Description clearly states 'Permanently delete an alert rule' with a specific verb and resource. It distinguishes from sibling tools like delete_ignore_rule and save_alert_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?

No when-to-use or alternative guidance is provided. The 'WRITE: available to any authenticated user' note addresses access but not when to choose this over set_alert_rule_status or save_alert_rule.

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 annotations provided, the description carries the full burden. It discloses key behavioral traits: permanent deletion, irreversibility ('This cannot be undone'), and the side-effect of stopping scheduling. This is comprehensive for a delete 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?

Two concise sentences deliver the core message and alternative guidance. No filler, front-loaded with the action, 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?

Given the simple one-parameter delete operation, no output schema, and minimal annotation support, the description is complete: it defines the action, emphasizes irreversibility, and provides a clear alternative for non-permanent scenarios.

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

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

The input schema already fully documents the only parameter (apiTestId: 'Id of the API test to delete') with 100% coverage. The description adds no additional parameter-specific semantics beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the tool's action: 'Permanently delete an API test and stop scheduling it.' This specifies the verb (delete), resource (API test), and distinguishes it from siblings like disable_api_test and enable_api_test.

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

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

The description explicitly says when to use this tool versus an alternative: 'use disable_api_test if you only want to pause it temporarily.' This provides clear context for when not to use it and directs to the appropriate alternative.

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

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

With no annotations provided, the description carries the full burden. It discloses the critical behavioral trait that deletion fails if the credential is referenced, which is essential for the agent to anticipate errors. It does not mention irreversibility or success responses, but the key failure mode is well-covered.

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 two sentences, front-loaded with the primary action, and immediately provides the crucial caveat. There is no redundant phrasing or unnecessary detail, making it highly concise and well-structured.

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

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

For a simple single-parameter delete operation, the description is sufficiently complete: it states what it does, the key precondition, and the consequence of ignoring it. No output schema exists, so no return-value explanation is required, and the coverage adequately supports agent decision-making.

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

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

The input schema already describes the sole parameter (`credentialId`) with 100% coverage. The description adds negligible semantic value beyond the schema, simply restating that deletion is by id. 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 clearly states the action ('Delete') and the resource ('a stored credential by id'). It is easily distinguishable from sibling tools that handle other resources (alert rules, ignore rules, API tests) and from create/list API test credentials.

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

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

The description explicitly mentions the failure condition ('Fails if any API test still references it') and provides clear guidance on what to do first ('reassign or delete those API tests first'). This effectively communicates when to use this tool versus first modifying API tests, though it does not name alternative tools explicitly.

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 annotations, the description carries the full burden. It explicitly discloses the operation type ('WRITE') and required permission ('requires the ADMIN role'), and explains the consequence on burn-rate alerts. This goes beyond a bare 'delete' statement, though it stops short of mentioning irreversibility or error handling.

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 the core action and effect front-loaded and the auth requirement neatly appended. Every word serves a purpose, with no redundancy or filler.

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

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

For a simple single-parameter delete tool with no output schema, the description adequately covers purpose, effect, and authorization. It does not detail irreversibility or error behavior, but these are largely inferable from the name and schema, making the description sufficiently complete.

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

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

Schema coverage is 100% and the single 'id' parameter is well-described in the schema (UUID, source). The tool description adds no extra parameter meaning, so baseline 3 applies.

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

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

The description clearly states the action 'Remove an ignore rule' and explains the functional outcome ('its fingerprint counts toward burn-rate alerts again'). This is specific to the resource and distinguishes it from siblings like create_ignore_rule and delete_alert_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?

Usage context is implied (reversing a prior ignore to re-enable alerts) but not explicitly stated as 'use this when...' Nor does it mention alternatives or exclusions. The 'again' hints at the reversal, but no direct guidance is provided.

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

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

The description discloses key behavioral traits beyond any annotations: it's a static catalog (reads no telemetry), returns the same answer for every caller, and is available to any authenticated user. Since no annotations are provided, the description fully covers the behavioral burden.

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

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

The description is well-structured and front-loaded with the core purpose. The extra guidance about the alternative tool and usage order is provided in a separate sentence, making it easy to scan. No wasted words.

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

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

For a tool with zero parameters and no output schema, the description is exceptionally complete. It explains what the tool returns, its behavior (static), its access level, and how it relates to sibling tools. No gaps remain.

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 and the schema description coverage is 100%, so there is nothing for the description to add about parameters. The description explains why no parameters are needed and provides all necessary context about what the tool returns.

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

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

The description clearly states the tool returns the static measure catalog for authoring alert rules, per source (LOGS, SPANS, METRICS), including measure functions, units, and defaultMode. It distinguishes itself from siblings like describe_schema and query's describe_schema by explicitly stating it no longer returns tenant services, groupable fields, or metric names.

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

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

The description provides explicit guidance: call query's describe_schema first to get tenant services, groupable fields, and metric names, then use this tool only to pick a measure once you know the source and, for METRICS, the metric's kind. This clearly tells when to use it versus 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?

With no annotations, the description carries the burden. It discloses the tool's behavior as an informational guide, listing its content areas. The phrase 'complete guide' and the imperative 'Call this once' imply a safe, read-only operation. It could explicitly state it has no side effects, but for a describe-style tool, the behavioral transparency is strong.

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

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

The description is concise yet dense, packing relevant information into three sentences. It front-loads the core purpose ('complete guide') and follows with a clear list of covered topics and a usage instruction. Every sentence earns its place with no redundancy.

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

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

Given no input schema, no output schema, and no annotations, the description fully compensates by explaining the tool's scope and usage. It covers what the guide contains, when to call it, and its relationship to mint_dashboard. This is complete for a zero-parameter informational tool.

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

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

The tool has zero parameters, so the description need not explain parameter usage. Baseline for 0 params is 4. The description focuses entirely on what the tool provides, which is appropriate.

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

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

The description clearly identifies the tool as a comprehensive guide to composing Fixter dashboards, listing specific aspects it covers (definition format, panel kinds, chart forms, grid layout, units, environment scoping). It distinguishes itself from siblings like mint_dashboard (which creates) by explicitly mentioning what mint_dashboard validates, 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?

Usage guidance is explicit: 'Call this once before composing your first dashboard in a conversation.' This tells the agent exactly when to use it. However, it does not explicitly state when not to use it or name alternative tools, though it implicitly differentiates from mint_dashboard by referencing its validation role.

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

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

No annotations exist, so the description carries the full burden—and it delivers. It discloses the return content (services with volumes, field profile, GROUP BY verdicts, measures, functions), the default data source (logs), the behavior of metrics pagination (metricsMatched shows true total), and restrictions (subqueries not allowed). It also explains the resource. prefix convention and dynamic attribute usage, which are key behavioral details.

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

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

The description is longer than average but each sentence provides useful details: purpose, usage sequence, field profile contents, metrics specifics, and filter semantics. It is front-loaded with the core purpose and then layers detail logically. A slight deduction because some details (like dynamic attributes and resource prefix) could be organized more compactly, but there is no fluff.

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

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

With no output schema, the description must explain return values—and it does thoroughly. It lists what the agent will receive: services with volumes, field profiles, type/coverage/distinct values/top values, GROUP BY verdicts, measures with fn/label/unit/defaultMode, and QuerySQL functions. It also explains the metrics bounding behavior and filter constraints, making the tool fully understandable without needing additional documentation.

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

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

The schema already describes all 5 parameters with 100% coverage, so the baseline is 3. The description adds contextual meaning for source (defaults to logs), service (drill into one service), prefix (only for metrics, reaches past bounded list), and filter (QuerySQL with same field names as run_sql, no subqueries). However, the 'path' parameter is not explicitly mentioned in the description, although its purpose is somewhat implied by the field-discovery focus. Overall, it adds value beyond the schema.

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

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

The description opens with a clear, specific verb+resource: 'Discover the queryable fields, functions, and measures for a data source.' It also distinguishes itself from the sibling tool run_sql by explicitly stating 'Use this before run_sql to learn what's available.' This makes the tool's purpose immediately understandable and unique.

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: 'Use this before run_sql.' It also describes a usage flow: call with no arguments to start, then optionally pass service=<name> to drill into one service. It provides conditional guidance for metrics (prefix to reach past the default page) and filter semantics. This leaves no ambiguity about how to invoke 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?

With no annotations provided, the description carries the full burden and succeeds: it discloses the state change to PAUSED, the side effect of no new runs being recorded, reversibility via enable_api_test, and the return value (updated API test). This gives the agent a complete behavioral model beyond the bare operation name.

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: the verb and object appear immediately, and the two sentences provide only necessary details (state, schedule impact, reversibility, return). No filler or redundancy.

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

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

For a simple tool with one well-documented parameter and no output schema or annotations, the description covers all relevant aspects: purpose, effect, reversibility, and return value. It is complete enough for an agent to decide when to call it and what to expect.

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

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

The schema already documents the single parameter apiTestId with a clear description ('Id of the API test to disable'), and schema coverage is 100%. The tool description adds no extra meaning or format details, so it meets the baseline for high schema coverage without surpassing it.

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

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

The description clearly states the action ('Disable (pause)') and the specific resource ('API test'), with the scope of 'stops running on its schedule.' It distinguishes itself from siblings like enable_api_test and delete_api_test by explicitly describing the paused state and the behavior of not recording new runs.

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

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

The description implies usage context: use when you want to pause an API test, and it explicitly references enable_api_test for resuming, which hints at the alternative. However, it does not explicitly exclude destructive alternatives like delete_api_test or state when this is preferred over deletion, so it stops short of full usage guidance.

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

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

With no annotations provided, the description carries the burden. It transparently states that the test will resume on its interval, reset state to UP, and return the updated API test. This covers the key behavioral outcomes, though it doesn't address edge cases like already-enabled tests or required permissions.

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 the action and purpose in the first sentence and details in the second. No unnecessary words or repetition.

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

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

For a simple tool with one parameter, the description covers the action, behavioral effect, and return value. It lacks explicit mention of what happens if the test is not paused, but this is a minor edge case.

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 apiTestId is fully described in the schema as 'Id of the API test to enable.' The description adds no further detail about the parameter (e.g., format, source). With 100% schema coverage, the baseline of 3 applies.

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

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

The description clearly states the action (enable/resume scheduling) and the target resource (a paused API test), and explains the effect (starts running, state resets to UP). This distinguishes it from sibling tools like disable_api_test and update_api_test.

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

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

The description implies usage by specifying 'a paused API test', indicating the prerequisite state. However, it does not explicitly name alternatives (e.g., disable_api_test) or state when not to use it, so it falls short of full guidance.

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

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

With no annotations, the description carries the transparency burden. It discloses authentication requirements ('available to any authenticated user'), tenant scoping, and the exact content of the return value for both call modes. It does not mention error cases or side effects, but for a read-only fetch tool 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?

Two sentences, front-loaded with purpose, and every sentence earns its place. The description is compact yet informative, with no redundant wording.

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

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

For a simple one-parameter read tool with no output schema, the description covers operation modes, authentication, tenant scope, and return contents. It is complete enough for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, and the description repeats the schema's guidance about omitting vs. supplying ruleId. It adds context about the response (full rule definition fields), but no new parameter-specific meaning beyond what the schema already conveys. 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 opens with a specific verb ('Fetch') and resource ('alert rules'), clearly scoped to the calling tenant. It distinguishes the two operational modes (list vs. single fetch) and differentiates from sibling tools like list_ignore_rules or delete_alert_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 provides clear context: it is a READ operation available to any authenticated user, and explains when to omit or supply ruleId. While it does not explicitly name alternative tools, its 'READ' label and explanation of behavior make appropriate usage unambiguous.

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

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

Even with no annotations provided, the description discloses what the tool returns: full configuration, health state (UP/DOWN/PAUSED), and consecutive-failure count. This adequately conveys the read-only nature and output scope for a simple fetch 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 a single, front-loaded sentence that states the primary action (fetch by id) and the key return contents. Every word earns its place with no redundancy or filler.

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

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

For a simple read operation with one parameter and no output schema, the description covers the essential ground: what it does, what it fetches, and what the response includes. No additional context (pagination, errors, side effects) is necessary for this tool's complexity.

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

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

Schema coverage is 100% and the sole parameter 'apiTestId' is already described clearly in the schema. The tool description adds no additional semantic value beyond echoing 'by id', so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Fetch') and resource ('API test'), clarifies it fetches a single test by ID, and distinguishes it clearly from siblings like list_api_tests and get_api_test_runs by emphasizing the single-item scope.

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

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

The phrase 'by id' gives clear context for when to use this tool—when you have a specific API test ID and need its full configuration/health. It doesn't explicitly name alternatives or exclusions, but the single-item focus compared to sibling list/get-runs tools makes the intended usage 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool supports pagination ('Page through'), includes outcome classifications, and provides filter capabilities. It does not cover auth, rate limits, or exact response shape, but for a list/read operation the disclosed behavior is reasonably 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?

The description is two sentences, front-loaded with the verb and resource, and every phrase earns its place. It efficiently conveys purpose, content, use case, and optional filters without waste.

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 has moderate complexity with six parameters and no output schema. The description explains what data is returned (outcomes, timing, assertion failures), the use case, and optional filters. It lacks explicit ordering or pagination defaults, but those are present in the schema. Overall it is sufficient for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters. The description adds value by summarizing that time window and status filtering exist, but it doesn't add syntax or details beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description uses a specific verb ('Page through') and resource ('API test's recent run history') and clearly lists the data returned (outcomes, timing, assertion failures). It distinguishes itself from sibling tools like get_api_test (single test) and list_api_tests (list tests) by focusing on run 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?

The description explicitly states when to use the tool: 'Use this to investigate why an API test is unhealthy.' It provides clear context but does not explicitly mention when not to use it or name alternative tools, so it falls slightly 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?

With no annotations provided, the description carries the full burden. It discloses the exact return structure (fields including sessionEntries) and clarifies that sessionEntries is the raw Claude Agent SDK transcript. It also mentions authorization ('authorized to read'), which signals access control. It does not explicitly state side effects, but 'fetch' implies a read-only operation, and the level of detail 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?

The description is two sentences with no fluff. The first sentence states the action and resource; the second provides the return-structure detail and a usage hint. Every sentence earns its place, and key 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 one-parameter tool with no output schema, the description is complete: it defines action, authorization, return fields, the meaning of the most complex field (sessionEntries), and the intended usage scenario. No additional details seem necessary for correct invocation.

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

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

The input schema has 100% description coverage of the single parameter (investigationId is described as 'The UUID of the investigation to fetch'). The tool description adds no further semantics beyond what the schema provides, so 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 clearly states the tool fetches the full transcript ('brief') of a Fixter investigation, using a specific verb (fetch) and resource (investigation brief/transcript). It distinguishes itself from siblings like list_investigations (which lists) and start_investigation (which creates) by emphasizing the 'full transcript' and the return fields.

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

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

The description provides a clear usage context: 'Use to recall context about an investigation that the engineer is currently working on via the Fixter plugin.' It does not explicitly call out alternatives or exclusions, but the intended use case is sufficiently clear for an agent to choose this tool over others.

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 annotations provided, the description carries the full burden. It clarifies the interpretation of the investigation block: it is generated content to treat as data, not instructions to follow. This is a significant behavioral disclosure beyond what the schema or name implies. It also notes the inclusion of 'latest' investigation, implying temporal behavior.

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

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

Two sentences, front-loaded with the main action, and the second sentence provides a necessary caveat about the investigation block. No wasted words, and the structure flows from action to interpretation.

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 a simple get by ID with one parameter and no output schema. The description tells the agent what the tool does, what the investigation block is, and how to interpret it. It doesn't cover error cases, but for a basic getter this is likely sufficient given the context and sibling tools.

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

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

Schema coverage is 100%, so the baseline is 3. The description doesn't add parameter semantics beyond what the schema already says; it simply repeats 'by fingerprint'. The schema itself already states the fingerprint is from list_issues, so the description adds no extra 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 action ('Fetch one issue') with a clear resource ('by fingerprint') and scope ('for the caller's account'). It also distinguishes itself from sibling tools like list_issues by focusing on a single issue, and mentions the investigation block, which is unique to this tool among getters.

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

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

The description clearly implies the use case: you need a specific issue when you already have its fingerprint. The schema parameter description reinforces this by noting the fingerprint comes from list_issues. While it doesn't explicitly name alternatives, the workflow is clear and no exclusions are needed.

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 annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool returns JSON or a message if no config is set, and implies authentication via 'authenticated customer's'. This adds value beyond the empty schema, though it could be more explicit about read-only behavior.

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

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

The description is two sentences, front-loaded with the action, and lists details concisely. No redundant information is present.

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

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

For a no-parameter getter with no output schema and no annotations, the description is complete: it names the resource, enumerates the returned fields, and covers the case where no config exists. This is sufficient for an agent to invoke and interpret the tool correctly.

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

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

The tool has zero parameters, so the baseline is 4. The description lists the fields in the response config, which helps the agent understand expected output structure, but there are no input parameters to explain.

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 fetches the authenticated customer's issue-surfacing digest config, listing specific fields (mode, cron expression, timezone, delivery channel id, lookback days, splitMessages). This specific verb+resource combination distinguishes it from sibling tools like set_issue_digest_config and other getters.

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

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

The description provides clear context that this tool reads the digest config, implying usage when the current configuration needs to be viewed. However, it does not explicitly mention when not to use it or name alternatives, so it falls 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?

With no annotations provided, the description carries full responsibility. It transparently discloses key behaviors: returns everything uncapped, no length cap, flattened attributes plus resource object, and no verbose/maxStringChars knobs. It could mention error handling (e.g., invalid logId) but the core behavioral traits are well covered.

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

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

The description is compact and front-loaded with the primary action. Each sentence adds value: purpose, usage context, behavior clarification, and a return type. No redundant or filler content.

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

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

For a simple one-parameter tool with no output schema or annotations, the description is complete. It covers what the tool returns, when to use it, its full-fetch behavior, and an alternative for column selection. Everything needed for correct invocation is present.

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

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

Schema description coverage is 100% (logId described as 'ULID of the log to fetch'). The description adds no further parameter detail beyond the schema, but it reinforces the purpose of the parameter in context. This meets 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 clearly states the tool fetches a single log by logId, with a specific verb and resource. It distinguishes itself from sibling tools like `logs` (lean scan) and `run_sql` (custom column selection), making its purpose unique.

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

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

Explicit usage guidance is provided: 'Use after a lean `logs` scan when you need the complete body of one row.' It also gives an alternative tool for different needs ('For custom column selection use run_sql'). This fully addresses when and when not to use the tool.

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

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

Since no annotations are provided, the description carries the full burden. It discloses defaults (3/3/true), strict ordering, source scoping, and return structure. It does not cover error cases or rate limits, but for a read-only query tool it is substantially transparent.

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 well-organized and front-loaded: purpose in the first line, then design, defaults, cross-pod variant, and return fields. Every sentence earns its place without unnecessary verbosity.

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 appropriately explains return fields (anchor, before, after, queryStats). It covers defaults, scoping, and the alternate sameSource=false mode, making it complete for a 4-parameter read tool.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond raw parameter definitions: it explains 'strictly older/newer', provides defaults, and clarifies the sameSource scoping rationale. This enriches all four parameters.

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

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

The description clearly states the tool returns logs chronologically around a given logId, with specific scoping by sourceInstanceId. It differentiates from siblings by emphasizing the neighbor context and avoiding interleaved replicas, making it distinct from a plain get_log or logs query.

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 names the target use case ('what happened right before/after this alert?') and explains when to use sameSource=false for cross-pod queries. This provides clear guidance on when to use the tool and when to adjust its primary setting.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It explains the return structure (channelIds), the meaning of null (fallback to defaults) and empty list (notifications off), and notes the authenticated customer context. It does not cover error handling or potential missing permissions, but the described behavior is sufficiently clear for a simple read 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 three sentences, each providing essential information: the purpose, the return format, and the interpretation of null/empty values. It is front-loaded with the core purpose and avoids redundancy. No fluff.

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

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

Given a single parameter and no output schema, the description sufficiently explains the two key edge-case behaviors (null and empty list) and the default fallback. It could also mention potential error responses or non-issues sources, but the current level of detail is adequate for typical usage.

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 description for the 'source' parameter is already highly detailed, covering valid values and constraints (issues vs alerting). The description adds value by explaining the output behavior tied to that parameter but does not add new semantic information about the parameter itself. The schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states the tool's function: showing which notification channels a source's notifications are delivered to for the authenticated customer. It specifies the resource (notification channels) and the scope (per source), and implicitly distinguishes it from the setter sibling tool (set_notification_routing).

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

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

The description provides context on when to use this tool by explaining the routing behavior, including the fallback for null and the disabling for empty lists. It also explicitly states that only 'issues' is routable and alerting is rejected, which is a clear exclusion. However, it does not name alternative tools for similar purposes.

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 annotations, the description carries full burden and excels: it discloses span ordering, parentSpanId for tree rebuilding, summary fields, default vs verbose behavior, string capping, and the shareable traceUrl. It also explains how to use traceUrl as evidence, adding actionable 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 front-loaded with the core purpose, then provides usage guidance and behavioral details. Every sentence contributes distinct information; no filler or repetition. The length is justified by the tool's complexity.

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

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

Given the absence of annotations and output schema, the description is remarkably complete: it specifies return fields, ordering, default behavior, verbose options, and when to use alternatives. It fully compensates for missing structured metadata.

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%, but the description adds value beyond the schema: it details that verbose includes 'attributes (flattened in, plus a `resource` object)' and notes that long string values are capped. This enriches parameter understanding.

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: 'Return every span in a single trace (up to 10000), plus a trace summary.' It clearly states the tool's function and distinguishes it from the sibling 'correlate' by noting it returns only spans without logs/exemplars.

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

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

Explicit guidance is given: 'Prefer correlate when investigating a trace... Use get_trace only when you need the span tree alone and want to skip the log/exemplar lookup.' This names the preferred alternative and specifies when to choose this tool instead.

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

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

No annotations are provided, so the description carries the burden of behavioral transparency. It notably discloses the exact uptime formula and explicitly excludes ERROR and MISSED runs, which is valuable beyond the tool's name. Although it does not explicitly state 'read-only', the verb 'Compute' strongly implies a non-mutating operation, and the formula detail adds genuine transparency.

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

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

The description is three sentences, each earning its place: the first states the core purpose, the second defines the metric precisely, and the third clarifies the default window. It is front-loaded with the key action and resource, with no filler or repetition.

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

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

Given the moderate complexity, full schema coverage, and absence of an output schema, the description is complete. It names the primary outputs, provides the exact calculation rule, and explains how window parameters behave by default. An agent has enough information to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description adds value by confirming the default window behavior ('Defaults to the last 24 hours'), but this largely reiterates what the parameter descriptions already state. Thus, it meets the baseline without significantly surpassing it.

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

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

The description begins with a specific verb ('Compute') and identifies the resource ('an API test's uptime percentage') along with additional outputs (latency percentiles, run counts). It clearly distinguishes this aggregated metrics tool from siblings like get_api_test_runs by focusing on uptime calculation rather than raw runs.

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 clear context: it computes uptime over a window and defaults to the last 24 hours when no window is provided. It does not explicitly name alternatives or exclusions, but the scope is evident enough for an agent to know when aggregation is needed versus other test operations.

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 annotations, the description fully discloses behavior: it returns JSON, explains the semantics of `id`, `channelId`, and `sources` (including null meaning all sources including future ones). It clearly implies a read-only operation and provides essential field-level context without contradictions.

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

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

The description is two sentences, front-loaded with the main action, then efficiently packs necessary details about field semantics and usage. Every sentence earns its place with no redundancy or 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 no annotations, no output schema, and zero parameters, the description is self-sufficient. It covers the operation, output structure, field meanings, and how the data integrates with other tools. This is complete for an agent to use the tool correctly without additional information.

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

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

There are zero parameters, so the baseline is 4. The description goes beyond by explaining the output fields (`id`, `channelId`, `sources`) and their significance, preempting potential confusion about the data structure, which adds substantial value beyond the empty schema.

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

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

The description clearly states the tool lists the authenticated customer's registered notification channels (Slack or email). It uses a specific verb ('List') and identifies the resource ('registered notification channels'), distinguishing it from sibling tools like add_alert_channel and remove_alert_channel.

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?

While it doesn't explicitly compare to alternatives, it explains how the output `id` should be used in other tools (save_alert_rule/set_alert_rule_delivery) and clarifies the difference between `id` and `channelId`. This provides clear context on when to use the tool and how to apply its results, though it doesn't state when not to use 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?

With no annotations, the description discloses a critical behavioral trait: secret material is never included. It also states the returned fields, giving the agent expectations about the response. It could mention permissions or pagination, but for a read-only list, 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?

The description is two concise sentences. The first delivers the main action and scope, the second adds a usage note. Every sentence earns its place with no redundancy.

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

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

For a zero-param tool without an output schema, the description fully covers the purpose, output shape, security guarantee, and downstream use. It is self-contained and leaves no significant gaps.

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 does not attempt to explain parameters and instead focuses on the output and usage, which is appropriate.

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

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

The description clearly states the tool lists stored credentials with the specific fields id, name, and type. It distinguishes itself from sibling credential tools like create/delete by focusing solely on listing.

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

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

It provides clear usage context: use the returned id to attach a credential to an API test. It doesn't explicitly mention alternatives or when not to use it, but for a simple list tool with no params, this is sufficient 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?

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It reveals the output fields and implies read-only behavior by listing, but does not explicitly state side-effect freedom, pagination, rate limits, or authentication requirements. It adds some transparency about the health state fields but could go further.

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: the first states the action and output, the second states the purpose. No wasted words, front-loaded with the verb and resource.

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

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

For a zero-parameter list tool with no output schema, the description is fully sufficient. It specifies what the tool returns (configuration, health state, failure count) and when to use it, making the tool's behavior clear.

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

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

The tool has zero parameters, and schema coverage is 100%, so no parameter explanation is needed. The description adds useful context about the scope ('all of your API tests') beyond the schema.

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

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

The description clearly identifies the tool as listing all API tests with specific output fields (configuration, health state, consecutive-failure count). It distinguishes itself from sibling tools like get_api_test, which retrieves a single test, and other API test management 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 says 'Use this to see what is being watched,' providing a clear use case. It does not explicitly mention alternatives or exclusion criteria, but the context is sufficient for a list-all 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?

With no annotations, the description carries the full burden. It explicitly states 'READ: available to any authenticated user', disclosing the read-only nature. It also details the content of each entry, including null meanings for operation and expiry, which is helpful behavioral context.

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

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

The description is very concise: two sentences that front-load the core purpose and then provide essential return-value details. Every sentence earns its place with no redundancy.

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

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

For a simple listing tool with no output schema, the description is complete. It covers the operation, scope, and the structure of the response, ensuring the agent understands what to expect.

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

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

The tool has 0 parameters, and the schema coverage is 100%. The description adds value by explaining what each entry shows, which complements the empty property list. Baseline for 0 params is 4, and this description meets it.

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

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

The description clearly states 'List the calling tenant's ignore rules' with a specific verb and resource. It distinguishes this tool from siblings like list_suppressions by explicitly naming ignore rules and the tenant scope.

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

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

The description provides clear context by labeling it as 'READ: available to any authenticated user', implying a safe read operation. It does not explicitly name alternatives or exclusions, but the context is sufficient for an agent to understand when to use this tool.

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

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

With no annotations provided, the description carries full burden, and it does well by explicitly stating that credential values are never returned and are write-only. It also discloses the response type (JSON), but does not mention error handling, pagination, or authentication requirements beyond the implied 'authenticated customer'.

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

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

Two sentences, no wasted words. The first sentence packs the core purpose and output structure, and the second sentence adds a critical security caveat 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 simple no-parameter tool, the description covers the essential return values and the JSON format. It lacks details like sorting order or empty-list behavior, but these are minor given the tool's low complexity and the richness of the description relative to the empty schema.

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

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

The tool has zero parameters, so the schema is trivially satisfied and the baseline is 4. The description adds meaning by explaining the output grouping and fields, which is helpful even though no parameter documentation is needed.

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

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

The description clearly states the tool lists the authenticated customer's stored monitoring credentials, grouped by provider, with specific fields (provider name, key names, updated-at timestamp). This is a specific verb+resource combo that distinguishes it from sibling tools like list_api_test_credentials and list_investigation_alert_channels.

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 viewing stored monitoring credentials but does not explicitly state when to use it over alternatives or provide exclusions. It lacks mentions of sibling tools such as list_api_test_credentials, leaving the agent to infer the distinction from the name and 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?

With no annotations provided, the description fully discloses the output shape (JSON array with specific fields), ordering, flow restriction, and how the IDs relate to sibling tools. It even clarifies that claimedBy is null when unclaimed. This is exemplary for a list tool and leaves no behavioral surprises.

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 dense paragraph that packs in all key details without fluff. It could be slightly improved with better sentence segmentation, but every sentence earns its place given the absence of an output 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?

The description is comprehensive for a list tool with no output schema: it defines the return structure, fields, scope, filters, and related tools. No major gaps are evident; edge cases like empty results or error handling are not addressed but are not critical for a well-specified list operation.

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

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

Schema coverage is 100% for all three parameters (to, from, limit). The description adds the clarification that 'from'/'to' bound createdAt and are optional ISO-8601 instants, supplementing the schema. The default and max for limit are already in the schema, so the description adds minimal but non-zero value; a 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 uses the specific verb 'List', names the resource 'Fixter investigations', and clearly states the scope ('authenticated customer's recent'), the flow restriction ('alert-investigation and product-support flows only'), and ordering ('newest first'). This fully distinguishes it from sibling list_* tools and leaves 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 provides actionable guidance by noting that the returned id feeds get_investigation_brief and start_investigation, and that publicSlug feeds start_investigation only. It also scopes usage to two specific flows. While it does not explicitly name alternatives or when-not-to-use cases, the context is clear enough for an agent to decide when to invoke this tool.

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

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

With no annotations provided, the description carries the transparency burden. It discloses filterable statuses, kind semantics (EXCEPTION for thrown errors and agent failures, LOG for log-derived issues), sort options, and the hasInvestigation flag. It does not mention rate limits or pagination, but for a list tool this is a reasonable level of behavioral disclosure.

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

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

The description is two sentences, front-loaded with the core purpose, then efficiently enumerates filters and sort options. It also includes a cross-reference to get_issue. Every sentence adds value with no redundancy or filler.

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

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

Given the tool's moderate complexity, the description covers the main capabilities, filter semantics, sort options, and return flag. It lacks an output schema, but mentions hasInvestigation and the next step (get_issue), which adequately completes the context for an agent to select and invoke the tool. Slightly more detail on result format would push it higher, but it's sufficient.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value beyond the schema by explaining kind values ('EXCEPTION for thrown errors and agent failures, LOG for issues derived from log lines') and clarifying the free-text query scope. This goes beyond mere parameter names, hence a 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 starts with a specific verb+resource+scope: 'List production issues for the caller's account.' This clearly distinguishes it from siblings like get_issue (single issue) and list_investigations. The filtering and sorting capabilities are also stated, making the tool's 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 provides clear context for when to use the tool (listing issues for the caller's account) and hints at an alternative by saying 'call get_issue to read it' for the investigation brief. It does not explicitly state when not to use it, but the context is sufficiently clear for an agent to choose it over related list tools.

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 annotations, the description carries the full burden. It discloses key behavioral traits: the one-entry-per-(service, metric) expansion, the meaning of each entry's fields, the per-service lastSeen semantics, and filtering behavior. It does not mention response limits, authentication, or error cases, but the core behavior is well covered.

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 well structured and economical: it starts with the core purpose, then explains usage context, then lists params, and finally states the return type. Every sentence earns its place without redundancy or fluff.

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

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

For a list tool with three optional params and no output schema, the description provides a complete picture: the return format, entry cardinality, field meanings, filtering options, and even a specialized use case. The only minor gaps are lack of pagination/limit details and error behavior, but these are not critical for initial tool selection.

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

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

The input schema already describes all three parameters with clear definitions (e.g., 'Filter to a specific service name', 'ISO-8601 instant inclusive/exclusive'). The description adds minimal extra value by framing the time window as 'seen within the range', but it does not introduce format details or constraints 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 clearly states the tool lists available metrics with a specific per-(service, metric) pair structure. It distinguishes itself from the sibling 'metrics' tool by explicitly saying to use it 'before calling metrics' and by clarifying the unique entry expansion behavior.

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

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

It explicitly instructs to use this tool to discover metrics and which services emit them before calling metrics, and it names an alternative tool. It also provides a concrete use case (dead-emitter detection) that helps the agent decide when it's appropriate.

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 annotations, the description carries the full burden. It explains the meaning of null fields for scope and expiry, defines severity caps, and indicates the operation is read-only and accessible to all authenticated users. It does not mention pagination or top-level response structure, but these are minor for a simple list.

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 main purpose in the first sentence, and the second paragraph adds concise but valuable context about null semantics and severity caps. 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?

Since there is no output schema, the description appropriately explains the key response fields (scope, severity cap, expiry) and the meaning of null values. It does not specify whether the return is an array or if there is pagination, leaving minor ambiguity, but overall it is sufficiently complete for a zero-parameter read-only 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?

The tool has zero parameters and the input schema is empty with 100% coverage. The description does not need to add parameter details, and the baseline of 4 for zero-parameter tools applies.

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

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

The description clearly states the tool lists active alert suppressions for the calling tenant, using the specific verb 'list' and identifying the resource. This distinguishes it from siblings like suppress_signal/unsuppress_signal and list_ignore_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?

Provides a 'READ' note and access information ('available to any authenticated user'), giving some context for when to use the tool, but does not explicitly mention alternatives or exclusion criteria. The implied usage is to view active suppressions, but better differentiation from list_ignore_rules would be useful.

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?

No annotations were provided, so the description carries the full burden—and it does so thoroughly. It discloses sorting order, default field selection, verbose behavior, string truncation, open time-window warning, pagination (nextCursor), and the explorerUrl semantic (sharing/citing evidence). This substantially exceeds the schema's mechanical descriptions.

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 well-structured, scannable, and every section adds value: one-line summary, default-start recommendation, return field summary, defaults, and common patterns. Despite the length, it avoids fluff and organizes information for efficient agent parsing.

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

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

This is a rich 10-parameter tool with no output schema and no annotations; the description covers function, time-range semantics, limits, unsupported behavior, and all relevant return fields including pagination and explorerUrl. It is complete enough to confidently invoke and correctly select it among 50+ sibling tools.

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

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

Schema coverage is 100%, so per calibration baseline is 3; the description adds meaning beyond the schema for some parameters (e.g., default from/to open window, limit max, messageContains whole-token semantics and run_sql alternative). It does not explain cursor/verbose/maxStringChars in much depth beyond the schema, but the usage patterns elevate it above the baseline.

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

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

The description clearly states the tool finds logs matching filter criteria within a time range, and distinguishes it from siblings by noting it is the default starting point for log queries. It also explicitly names alternatives (run_sql for raw columns/custom selection, get_log for full untruncated body), resolving ambiguity among log-related 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?

Provides explicit when-to-use guidance ('default starting point for log queries') and excludes alternatives for substring/regex or raw columns, with named alternatives: run_sql and get_log. Common patterns show concrete scenarios (errors in last hour, trace id, whole-token search), plus behavior such as open time window and limit defaults.

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 annotations provided, the description carries the full behavioral burden and excels: it discloses how output varies by metric type, the rule that groupBy/filters only apply to data-point attributes with a key regex, server-side step coarsening semantics, and the exact conditions under which explorerUrl is null. This is far beyond a minimal hint.

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

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

The description is long but every section serves a purpose: the metric-type list, parameter semantics, and return/coarsening details are all essential for correct use. It is front-loaded with the core purpose, then organized by logical sections, making it easy to scan despite its 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 (7 parameters, nested objects, no output schema), the description is exceptionally complete. It explains return fields, coarsening behavior, the authoritative 'step' field, and explorerUrl usage with caveats—covering both invocation and interpretation of results.

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

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

Although schema coverage is 100%, the description adds substantial meaning: metricName and service must be exact values from list_metrics, step has a specific syntax with unit examples and a minimum, from/to are inclusive/exclusive, groupBy/filters operate on data-point attributes, and filter values are safe to pass as-is. This transforms bare parameter names into actionable guidance.

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 clear verb and resource: 'Query a metric time series.' It distinguishes itself from sibling tools like logs, spans, and run_sql by focusing on metric queries, and the detailed breakdown of metric types (GAUGE, SUM, SUMMARY, HISTOGRAM) reinforces its unique purpose.

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

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

The description provides strong context for when to use the tool—whenever metric time-series data is needed—and clarifies scope with details like optional service aggregation and groupBy/filters constraints. It does not explicitly mention when not to use it or name alternative tools, but the purpose is clear enough to guide selection.

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

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

With no annotations, the description fully covers behavior: dashboards are immutable once minted, the tool refuses to mint broken definitions, it executes panel SQL against live data, and distinguishes between errors (blocking) and warnings (ship with handover). This goes far beyond schema details.

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

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

Although the description is multi-sentence, every sentence earns its place: purpose, prerequisite, immutability, validation steps, error handling, and composition advice. It is front-loaded with the main verb and well-structured for quick 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?

For a tool that executes SQL and mints URLs with no output schema, the description covers the complete workflow: prerequisites, validation behavior, success/failure semantics, and integration with sibling tools. There are no significant gaps.

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?

All parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds context that definitionJson follows describe_dashboards' schema, but it doesn't enrich range or refresh semantics beyond what the schema already provides.

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

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

The description clearly states the tool's purpose: 'Validate, ground, and mint a Fixter dashboard link.' It also distinguishes from siblings by referencing describe_dashboards for schema and run_sql for grounding, making it unmistakable what this tool does relative to others.

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

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

Provides explicit usage guidance: 'Call describe_dashboards before first use' and 'Compose with grounded queries (run_sql) first; this tool verifies, it does not design.' This gives clear when-to-use and when-not-to-use instructions, including 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?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: states it never persists anything, never throws for invalid specs, returns problems[] vs. warnings[] with distinct save implications, backtest is null for anomaly rules, and explains dataCoverage.status semantics and the FIELD_NEVER_OBSERVED warning code.

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

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

The description is long but highly information-dense; it is front-loaded with a one-sentence summary, then organized into modes, backtest interpretation, and return-value semantics. Every paragraph adds operational guidance, and the length is justified for a complex 20-parameter tool with two input modes and nuanced return 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?

Given no output schema and 20 parameters, the description compensates fully by explaining return fields (normalizedSpec, problems[], backtest, seasonality, warnings[]), their semantics, and edge-case behaviors like NO_MATCHING_DATA and FIELD_NEVER_OBSERVED. It gives enough detail for an agent to correctly call, interpret, and decide next actions without additional docs.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds substantial context beyond the schema: fromQuerySql overrides/ignores structured fields, zScoreThreshold/direction are mutually exclusive with comparator/warningThreshold, groupBy must be empty for anomaly mode, lookbackDays default of 7 with clamping, and windowMinutes minimum clamped to 5.

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?

Opens with 'The preview→save gateway: validates and normalizes a candidate rule spec and, when valid, backtests how often it WOULD have fired...' which gives a specific verb+resource+behavior. It explicitly distinguishes from save_alert_rule by framing as the pre-save validation/calibration step and notes it never persists anything.

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?

Directly instructs 'Call this before save_alert_rule to calibrate' and provides explicit decision guidance on how to interpret backtest.dataCoverage and when to fix the filter vs. adjust the threshold. It also states the two mutually exclusive input modes, static vs. anomaly conditions, and that anomaly backtest is not yet supported.

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 annotations provided, the description carries the full burden and does exceptionally well. It discloses the destructive cascade delete of bound auto-investigation rules and states that recovery is impossible. It also returns a confirmation message, adding important behavioral context.

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

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

The description is concise and well-structured. It leads with the action, then notes permissions, then highlights the critical warning, and ends with the return type. Every sentence earns its place with no redundancy.

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

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

Given the tool's simplicity (one parameter, no nested objects, no output schema), the description is complete: it explains the action, scope, permission, side effects, and return value. It provides all necessary context for safe invocation.

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

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

The input schema provides 100% coverage for the single parameter channelId, including an example. The description adds no additional parameter-specific details beyond the schema, so 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 clearly states the action: 'Remove a Slack channel id from the authenticated customer's notification-channel list.' This is a specific verb-resource pair that distinguishes the tool from siblings like add_alert_channel and list_alert_channels.

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

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

The description provides context by noting 'ADMIN only' and warns about the irreversible cascade deletion, which implies caution. However, it does not explicitly mention when not to use it or name alternative tools, so it falls 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses read-only enforcement, exact SQL limitations, zero-filling behavior for buckets, DISTINCT modifier semantics, case-sensitivity rules, metrics temporality caveats, and the response shape ('only rows, queryStats, and error'). This is far beyond minimal disclosure.

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

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

The description is long but every section earns its place: purpose, syntax, functions, examples, limitations, and alternatives. It is front-loaded with a clear one-line purpose and organized into logical blocks. There is no filler or repetition despite the length, which is justified by the tool's complexity.

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

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

Given no output schema and no annotations, the description is exceptionally complete. It covers data sources, common fields, custom functions, aggregation semantics, limitations, return shape, and alternative tools. An agent could select and invoke this tool correctly with high confidence.

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

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

The schema only says the sql parameter is 'A QuerySQL SELECT statement without trailing semicolon' with 100% coverage. The description massively enriches this by documenting supported syntax, functions, field names, examples, limitations, and nuanced behavior. It provides far more contextual meaning than the schema alone.

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

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

The description opens with a specific verb+resource: 'Execute a read-only QuerySQL SELECT against the observability data.' It clearly identifies the action, the query language, and the data scope, and it distinguishes this tool from siblings by positioning it as the ad-hoc querying option while naming alternatives like correlate and get_trace.

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 and when-not-to-use guidance: 'Use run_sql for ad-hoc analysis that the other tools don't cover,' 'Call describe_schema first,' and 'For a linkable log search, use the logs tool instead.' It also names purpose-built alternatives (correlate, get_trace, aggregate_spans) with their specific use cases.

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 annotations, the description carries full behavioral burden and does so thoroughly. It discloses that updates are whole-object replaces, that omitted fields are cleared, that status and delivery survive omission, that warnings are advisory while problems block persistence, and that the rule still saves with non-empty warnings. It also explains FIELD_NEVER_OBSERVED and the create-only nature of active and channelIds.

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

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

The description is long but appropriately sized for a 25-parameter tool with two rule types and nuanced update semantics. It is front-loaded with the critical whole-object-replace warning, then organized into METRIC RULE, ANOMALY METRIC, and Common fields sections. Every section 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?

Despite no output schema and no annotations, the description is remarkably complete: it covers authentication, validation behavior, problems[] vs warnings[], dataCoverage.status, rule-type constraints, field-level requirements, and explicit sibling-tool alternatives. It gives an agent enough context to safely invoke this complex write 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?

Although schema coverage is 100%, the description adds substantial semantic value beyond the schema: it explains required conditions like metricName/metricType only for METRICS, anomaly rules requiring empty groupBy, expression precedence over fn, unit-setting guidance for OTel names, and the rejection of channelIds together with ruleId. This goes far beyond the baseline schema descriptions.

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

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

The description opens with a specific verb and resource: 'Create or update an alert rule for the calling tenant in one call.' It immediately clarifies the create-vs-replace distinction via ruleId and explicitly contrasts with sibling tools like set_alert_rule_status and set_alert_rule_delivery.

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

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

Usage guidance is explicit and actionable: it names get_alert_rules for fetching full specs before update, preview_alert_rule for validation, set_alert_rule_status for status changes, set_alert_rule_delivery for routing changes, and the web editor for compound rules. It also states when not to use this tool, e.g., 'Compound multi-condition rules can't be created here.'

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 annotations provided, the description carries the full burden, and it excels. It discloses that the tool is a WRITE operation, clarifies that routing is the only affected aspect, explains exact error behavior ('INVALID_CHANNEL_ID and nothing is changed'), and details the replacement semantics including clearing to default. This is comprehensive and honest.

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 four sentences: the first states the purpose, the second covers safety and comparison to a sibling, and the third/fourth detail parameter semantics and behavior. Every sentence earns its place with substantive, non-redundant information.

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

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

For a two-parameter mutation tool with no output schema, the description is fully complete. It covers purpose, when to use, error handling, parameter meaning, and the effect on existing state. No additional context is needed for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explicitly mentioning the INVALID_CHANNEL_ID error for non-UUIDs and emphasizing that replacement is outright and empty-list resets to default, which reinforces the schema text with behavioral consequence. This goes beyond the schema's property descriptions, but the schema already includes the key UUID and empty-list notes, so the extra is incremental.

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

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

The description opens with a specific verb+resource combo: 'Replace the notification channels an existing rule's alerts are sent to.' It explicitly distinguishes itself from save_alert_rule by noting it only touches routing, not spec/thresholds/status. This makes the purpose unmistakable relative to sibling tools.

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

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

The description explicitly frames when to use this tool versus save_alert_rule, stating it is 'safe to call on a live rule and can't clobber a concurrent edit the way save_alert_rule's whole-object replace can.' It also warns against using Slack/provider channel IDs and directs to list_alert_channels, giving actionable guidance for correct invocation.

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 annotations provided, the description carries the full burden of behavioral disclosure. It discloses that this is a WRITE operation available to any authenticated user, and explains the meaning of ENABLED vs DISABLED (rule is evaluated or not). This provides meaningful behavioral context beyond the raw 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 concise and front-loaded: it states the purpose in the first sentence, then adds the WRITE permission and status semantics. Every sentence serves a distinct purpose, with no filler or repetition.

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

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

For a simple two-parameter tool with no output schema, the description covers the core operation well: it states the action, the allowed status values, and their meanings. It does not mention return values or error cases, but given the tool's simplicity and the absence of an output schema, the description is reasonably complete.

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

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

The input schema has 100% coverage for ruleId and status, so the baseline is 3. The description adds value by explaining what ENABLED and DISABLED actually mean ('the rule is evaluated' vs 'it is not'), which goes beyond the schema's simple 'ENABLED or DISABLED'. This semantic enrichment justifies a 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 clearly states the tool's function: 'Set an alert rule's status.' It identifies the resource (alert rule) and the specific action (setting status), and distinguishes it from sibling tools like set_alert_rule_delivery and save_alert_rule by focusing solely on the status field.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or cases where another tool (e.g., save_alert_rule) would be more appropriate. The only context is the WRITE note and status semantics, which are more about behavior than usage timing.

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 annotations, the description carries the full burden and does excellently. It discloses that the operation is mutating (create/overwrite), requires admin privileges, never returns the stored value, and rejects temporary STS credentials. This goes beyond what the schema provides and clearly sets 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?

Three sentences, each earning its place: purpose, requirement/constraint, and return behavior. It is front-loaded with the core function and immediately provides essential usage details. No filler.

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

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

Given the tool's simplicity (3 required params, no output schema), the description fully covers purpose, authentication requirements, parameter constraints, and expected response behavior. It lacks nothing critical for an agent to invoke the tool correctly and understand the outcome.

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 valuable context beyond the schema by explaining that all three parameters are required and that accessKeyId and secretAccessKey must be from a permanent IAM user (not STS). This gives meaningful guidance for choosing correct parameter 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 uses a specific verb ('Store') with explicit create/overwrite semantics, names the resource (AWS CloudWatch monitoring credentials), and clearly distinguishes from the sibling set_investigation_datadog_credentials by specifying 'CloudWatch'. It is unambiguous and precise.

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

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

Provides clear context: ADMIN only, and requires permanent IAM keys rather than temporary STS credentials. It implies that this tool is for CloudWatch credentials specifically, but it does not explicitly mention alternatives like set_investigation_datadog_credentials or when to choose one over the other, so it misses the full 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?

No annotations are present, so the description carries the full burden. It discloses the create/overwrite side effect, the ADMIN-only permission requirement, and the non-return of stored values (only a confirmation message). These are meaningful behavioral traits beyond the schema.

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

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

Three sentences, front-loaded with the primary purpose, and every sentence carries essential information: action, permission, required/optional params, and return behavior. No redundancy or filler.

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

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

For a simple credential-setting tool with no annotations and no output schema, the description covers all critical aspects: the action, permission, parameter requirements, and return behavior. It is self-sufficient and gives an agent enough context to invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats that apiKey and appKey are required and apiUrl is optional, but this adds no new meaning over the schema. No additional parameter semantics are provided.

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 ('Store (create or overwrite)') and the resource ('Datadog monitoring credentials'), making it specific and distinguishable from sibling tools like set_investigation_cloudwatch_credentials. The ADMIN only note also clarifies authorization scope.

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

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

The description implies use for setting Datadog credentials but does not explicitly name alternatives (e.g., set_investigation_cloudwatch_credentials or create_api_test_credential). It does provide a clear usage constraint (ADMIN only) and lists required/optional parameters, but the 'when to use vs alternatives' aspect is only implied.

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

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

With no annotations, the description carries the full burden and delivers: partial update semantics (omitted fields keep current value), validation (mode must be OFF/INTERNAL/LIVE), default behavior for non-existent configs, access requirement (ADMIN only), and return value (saved config as JSON). This is exemplary transparency for a mutation 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?

Four sentences, front-loaded with purpose and then behavioral details. Every sentence conveys necessary information with no redundancies or fluff. Perfectly sized for the tool's complexity.

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

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

The description covers all critical aspects: purpose, admin restriction, partial update behavior, mode validation, defaults for missing config, and return format. No gaps remain given the moderate complexity, no annotations, and no output schema.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the general partial-update contract and mode validation, which gives semantic context beyond individual parameter descriptions. It doesn't enumerate each parameter, but the schema already does.

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+resource: 'Create or update the authenticated customer's issue-surfacing digest config.' It distinguishes itself from sibling read tools like get_issue_digest_config and other set_* tools by specifying exactly what it modifies.

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 (to create or update a digest config) and includes an important prerequisite ('ADMIN only'). It doesn't explicitly name alternatives (e.g., 'use get_issue_digest_config to read'), but the create/update purpose is self-evident and distinct from 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?

With no annotations, the description must reveal side effects. It states that omitting channelIds clears routing and returns to default, and an empty list disables notifications entirely. It also mentions the return value. It does not explicitly say it modifies persistent state, but the behavior is sufficiently transparent.

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 well-structured, covering purpose, permission, usage, edge cases, and return value in a logical flow 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?

It explains the return value (saved routing as JSON) and covers critical behavioral nuances. Given the simplicity of the operation, it provides sufficient context for an agent to use the tool correctly.

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

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

Both parameters are explained thoroughly. The description explains that source is limited to 'issues' (from schema), and channelIds details the three cases (provide ids, omit to clear, empty list to disable) beyond the schema's brief description.

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

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

The description clearly states the tool sets notification routing for a source, distinguishing it from sibling get/list tools. It specifies the action (choose which channels) and the resource (source's notifications for authenticated customer).

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 explains when to use (to configure routing) and provides detailed behavior for different inputs (omit to clear, empty list to disable). It also notes ADMIN-only access. Could mention when not to use (e.g., read-only via get_notification_routing), but the usage context is clear.

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

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

With no annotations, the description carries the full burden and does so thoroughly. It discloses sorting order, default response fields, verbose behavior, string truncation, default time windows, limit defaults, and filter semantics. It also outlines the return structure (spans, nextCursor, queryStats), exceeding typical 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 well-organized with clear sections and front-loaded purpose. Every sentence contributes useful information, including common patterns and return details. Despite its length, it avoids redundancy and remains structured and scannable.

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

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

Given the tool's complexity (12 optional parameters, no output schema), the description is remarkably complete. It explains return values, default behaviors, filter semantics, and provides practical examples. It also covers when to use sibling tools, making it self-contained for effective selection and invocation.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds contextual value beyond the schema by illustrating parameter usage with examples (e.g., statusCode='ERROR', name='http.client', minDurationMs=500, traceId) and explaining default behaviors for limit, from/to, and verbose. It doesn't deeply elaborate every parameter, but the extra semantic context justifies a 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 clearly states the tool's function with a specific verb and resource: 'Find individual spans matching filter criteria within a time range.' It also distinguishes itself from siblings by explicitly positioning as a drill-down tool and referencing aggregate_spans and run_sql.

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

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

Provides explicit guidance on when to use this tool versus alternatives: 'For "where are errors / latency concentrated?" start with aggregate_spans' and 'For raw columns or custom selection use run_sql.' It also offers common usage patterns and mentions get_trace as an alternative for trace-level retrieval.

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 annotations, the description carries the full burden. It transparently discloses the key side effect: 'This CLAIMS the investigation (records the caller as claimant).' It also details what is returned, including the raw transcript. It does not mention what happens if already claimed or permission requirements, but the core behavioral trait is clearly disclosed, which is strong given no annotation support.

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

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

The description is dense but every sentence earns its place: purpose, identifier format, claiming warning, alternative tool, and return payload structure. It is front-loaded with the most important action and uses clear formatting (bold for CLAIMS) to highlight critical behavior. No filler words.

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

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

Despite having no output schema, the description lists all expected return fields (id, publicSlug, headline, flow, channelId, threadTs, createdAt, claimedBy, sessionEntries), eliminating ambiguity about the response. It also covers the side effect and the identifier format, making it self-contained for an agent to invoke correctly. For a simple one-parameter tool, this is exceptionally 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?

The schema already describes the parameter idOrSlug with 100% coverage. The description adds a concrete example ('happy-otter-42') and clarifies that both UUID and public slug are accepted, which enriches the schema text. For a single parameter, this is sufficient extra value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Claim a Fixter investigation for the calling user and fetch its full transcript.' It clearly states the two actions (claim and fetch) and the resource (investigation). It also distinguishes itself from the read-only sibling get_investigation_brief by emphasizing the claiming aspect, 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 provides explicit usage guidance: 'only call it when the user intends to work on the investigation' and names the alternative tool for read-only access ('use get_investigation_brief'). This directly tells the agent when to use this tool versus a clear alternative.

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

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

With no annotations, the description carries the full burden and does well: it explains that only notifications are muted (rule evaluation and dashboards unaffected), suppression is temporary and reversible, scope narrowing behavior, severity cap semantics, duration handling, and that only one suppression per scope is allowed. This exceeds typical transparency 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 well-structured with headings and front-loaded with the primary purpose. It is somewhat long but every line adds necessary behavioral detail for a 5-parameter tool. Would be a 5 if slightly more compressed.

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?

Covers purpose, usage alternatives, scope, severity, duration, and uniqueness. Lacks explicit mention of the success return value, but given no output schema and the availability of list_suppressions for verification, this is a minor gap. Overall highly complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the hierarchical scope (service > signal > operation), default/omit behavior for onlyWarnings and durationHours, and the uniqueness constraint. This goes beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool silences future alerts for the calling tenant, stopping paging without affecting the underlying alert rule. It distinguishes from siblings by naming create_ignore_rule (for excluding traffic from burn-rate evaluation) and unsuppress_signal (for reversal).

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 instructs when to use create_ignore_rule instead of this tool, and references unsuppress_signal and list_suppressions for managing suppressions. This provides clear context on alternatives and prerequisite actions.

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 annotations, the description must disclose behavioral traits. It states the auth requirement (WRITE, any authenticated user) and the effect, but does not mention idempotency, error behavior, or whether the suppression is permanently deleted. This is adequate but lacks depth.

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, focused sentences. The first states the action and effect, the second adds the auth constraint. No filler or redundancy.

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

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

For a simple one-parameter mutation tool with no output schema, the description covers the core purpose, effect, and auth. It could be more complete by addressing what happens with an invalid or missing id, but overall it is reasonably complete.

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

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

The schema provides 100% coverage for the single parameter 'id', including a clear description of its source. The tool description adds no additional parameter semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Remove') plus the resource ('alert suppression') and clearly states the consequence ('alerts for that scope resume paging'). This clearly distinguishes it from the sibling tool suppress_signal.

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 the tool (to lift an existing suppression and resume paging), and the schema context for id points to suppress_signal/list_suppressions. However, it does not explicitly name alternatives or state when not to use 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?

With no annotations, the description carries the burden of disclosing behavior. It explicitly states that this is a full overwrite, not a partial patch, which is a critical destructive trait, and it mentions the return value ('Returns the updated API test and its state'). This goes beyond a bare mutation description.

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

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

The description is three sentences, front-loaded with the action, then a critical caveat, and a return-value note. Every sentence adds value—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?

The tool has 27 parameters and no output schema or annotations, so the description needs to add context beyond the schema. It covers the core behavior (full overwrite), parameter handling guidance, and return value. While it could include an example or error conditions, the provided context is sufficient for selecting and invoking the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful semantic guidance by clarifying that because this is a full overwrite, every field intended to be kept must be supplied. It also points to create_api_test for parameter details, helping the agent understand the parameter set without repetition.

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

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

The description uses a specific verb+resource ('Replace the entire configuration of an existing API test') and clearly distinguishes itself from sibling tools like create_api_test by focusing on updating an existing test. The scope is unambiguous.

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

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

It provides clear context—this is for updating an existing API test via apiTestId—and emphasizes that it is a full overwrite, so users must pass all fields they want to keep. It does not explicitly list alternatives or when not to use it, but the context is clear and useful.

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