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 carries the behavioral burden and does so richly: it reveals the default reads a pre-aggregated rollup with specific resolution/retention (minute vs hourly, up to 400 days), that parent_operation is computed on demand over raw spans, and that truncation and zero-filled buckets occur under maxChars/step. It also clearly implies a read-only operation by describing reads and computations.

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 intentionally organized: purpose and use-case triggers are front-loaded, the parent_operation caveat appears early, and params/results are in compact labeled blocks. Every sentence conveys either a use decision, a performance characteristic, or a return-field fact; there is no filler.

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

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

For a 7-parameter tool with no annotations and no output schema, the description is comprehensive: it covers all parameters through the schema and the Params block, documents the full return shape (buckets fields, errorRate scale, quantileNanos, queryStats, truncation fields), and explains the zero-fill behavior. An agent has enough to choose and call the tool correctly and interpret 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?

Schema coverage is 100%, so the baseline is 3, and the description adds useful meaning beyond the schema: it documents the default groupBy ('service, operation'), gives concrete step examples, clarifies from/to as an ISO-8601 required window, and explains the behavioral effect of the parent_operation group key. It does not need to repeat every property, but the added semantics justify 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?

States a precise verb ('Aggregate spans') and a specific resource: RED metrics including request count, error rate, throughput, and latency percentiles, grouped by service/operation/parent_operation. It also distinguishes itself by pointing to raw spans tools ('spans / get_trace') for drill-down, so an agent can immediately tell it from 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?

Gives explicit start-here triggers for common questions ('where are errors / latency concentrated?', 'what changed between two windows?') and names alternatives: use spans/get_trace once pointed at a specific service/operation. It also warns to keep the on-demand parent breakdown scoped with a tight window 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 provided, the description carries the full burden of behavioral disclosure, and it does so well: it explains that variables are resolved once per run, unknown names are left as written, and how to escape a literal '{{'. It also discloses that the tool returns the created test with its id and state. It does not mention idempotency or side effects, but 'create' and 'returns the created API test' make the mutating nature clear.

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

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

The description is front-loaded with the core action and purpose, then moves to usage mode selectioncars. The variable list is long but necessary for this tool's correct use)Skip. Every sentence earns its place, and there is no filler or repetition of schema content.

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

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

Given 26 parameters, no annotations, and no output schema, the description provides a solid overall picture: what a test is, how to select HTTP vs MCP mode, variable resolution behavior, and what is returned. It does not exhaustively map every parameter dependency (e.g., when mcpTier/toolName are required together), but the schema already covers those details. The description is complete enough for an agent to form a correct mental model.

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 cross-parameter semantics (variable interpolation behavior, the HTTP/MCP mode split), but it contains an inaccuracy: it refers to 'httpTarget' while the actual property is 'httpUrl'. This minor error slightly undermines parameter guidance, so it stays at baseline rather than earning 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 a specific action ('Define an API test'), defines what the test is (scheduled probe of an HTTP endpoint or MCP server), and distinguishes this creation tool from siblings like update_api_test, delete_api_test, and list_api_tests. The first sentence alone tells the agent what resource this operates on and what it accomplishes.

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

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

The description gives clear usage context: 'Use this to start watching an HTTP endpoint or an MCP server' and conditions for HTTP vs MCP mode with concrete parameter pointers. It does not explicitly name alternatives for modification/deletion (update_api_test, delete_api_test), but the create-vs-manage distinction is strongly implied by the tool name and the 'start watching' framing.

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 behavioral burden. It clearly states the operation is permanent ('Permanently remove') and describes the consequence ('The link stops working for everyone holding it'). This goes beyond the schema and gives the agent a realistic expectation of the side effects, though it doesn't mention any other side effects or authorization requirements.

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

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

The description is two concise sentences with no filler. It front-loads the core action ('Permanently remove') and then provides the essential effect and condition. Every sentence earns its place 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 destructive tool with one parameter and no output schema, the description is fully sufficient. It explains what the tool does, the consequence, and when to use it. Nothing an agent needs to correctly invoke this tool is missing.

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

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

The input schema already documents the single 'id' parameter with 100% coverage, and the description adds nothing beyond that. The baseline of 3 applies because the schema fully handles parameter documentation; no additional compensation 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 'Permanently remove a stored dashboard' states a specific verb (remove) and resource (dashboard), and clarifies it is permanent and affects the link for all holders. This clearly distinguishes it from sibling deletion tools like delete_alert_rule or delete_api_test, which target different resources.

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

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

The description gives an explicit condition: 'Only call this when the user has asked for the dashboard to be removed.' This tells the agent when to invoke the tool. It doesn't mention alternatives (e.g., update_dashboard for modifications), but for a delete operation the condition is clear and 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?

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 must carry the behavioral load. It declares 'READ: available to any authenticated user' (auth trait), lists the returned fields, and explicitly notes that delivery destinations are not included. It stops short of mentioning error conditions or pagination, but for a simple fetch it is largely 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 organized in three distinct, purposeful blocks: purpose+auth, usage+return, and related tools. Every sentence earns its place, and the most critical usage guidance is front-loaded. 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?

For a tool with one optional parameter and no output schema, this description is remarkably complete. It covers authentication, invocation patterns, return content, and even points to the complementary tools for notification destinations, leaving no missing piece for an agent to call it correctly.

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

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

The input schema already provides a 100% descriptive coverage for ruleId ('Optional rule id (UUID); omit to list every rule'). The description repeats this guidance and adds the return-field context, but does not offer new parameter-specific semantics beyond what the schema states, so the baseline of 3 applies.

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

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

The description opens with a clear verb+resource pairing ('Fetch the calling tenant's alert rules'), which is specific and distinguishes it from sibling write/delete tools like save_alert_rule and delete_alert_rule. It further clarifies the two invocation modes (list vs. single rule), leaving no ambiguity about the tool's scope.

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

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

The description explicitly states when to use this tool (to fetch alert rules) and, crucially, when not to: it explains that notification destinations are out of scope and directs the agent to get_notification_destinations and set_notification_destinations with precise parameters. This is an exemplary 'when and when-not' guidance.

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

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

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, the description carries the behavioral disclosure burden and does so well: it explains traceId as the traceparent sent to the target, useful for correlating target logs, and notes that redacted request/response captures are available only via the HTTP API. It lacks details like sort order or auth requirements, but the core 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?

Each sentence earns its place: purpose and returned fields first, usage context second, filtering third, and the HTTP-only capture limitation last. The traceId clause is long but directly useful for downstream correlation, not padding.

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

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

Given no output schema and no annotations, the description compensates by naming the key returned fields enough for an agent to understand what it will get, and adds the important redacted-capture caveat. It omits secondary details like sort order and pagination metadata, but not enough to impair a correct call.

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

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

The schema already documents all six parameters at 100% coverage, so the baseline applies. The description adds only the high-level 'filter by time window and status' grouping and confirms the page-through behavior, without adding new parameter-level 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?

Description opens with a specific verb-resource pair, 'Page through an API test's recent run history,' and enumerates the fields returned (outcome, timing, assertion failures, traceId). This clearly separates it from sibling tools like get_api_test, which targets test configuration, by framing the resource as 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?

It explicitly says 'Use this to investigate why an API test is unhealthy' and mentions optional time/status filtering, giving a clear trigger context. It does not name alternatives or state when not to use it, so it stops short of full when/when-not guidance.

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

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

With no annotations, the description carries the safety burden. 'Return the stored definition' clearly indicates a read-only operation, and the compatibility with update_dashboard conveys the output's shape and purpose. It does not disclose possible error cases or any side effects, but for a simple read of one resource this is largely sufficient.

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

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

Two sentences with no filler: the core behavior is front-loaded, and the second sentence justifies the workflow with a concrete consequence. Every word earns its place.

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

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

For a one-parameter read tool with full schema coverage and no output schema, the description explains what is returned, why it is useful, and how it connects to update_dashboard. No critical information for calling it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents the id parameter and its source. The description adds only that the dashboard must exist, which is marginal over 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 names the exact action (return the stored definition), the resource (an existing dashboard), and the purpose (editing and handing to update_dashboard). This distinguishes it from list_dashboards/describe_dashboards, which return summaries rather than the full editable definition.

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

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

It explicitly says to call this before update_dashboard and contrasts it with rebuilding a definition from memory. This gives the agent a clear decision rule and warns against a costly 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does so thoroughly: samples are newest first, failures without a fingerprint leave no exception, includeSeries=true is large, unexplainedFailedCalls has a precise meaning, and the default time window is 21 days.

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, front-loaded, and free of filler; every clause adds needed behavior, especially since there is no output schema. However, it is written as a single long run-on paragraph, and splitting the payload description, the failure-investigation workflow, and the parameter guidance into distinct sections would improve scanability without losing 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?

With no output schema and no annotations, the description must fully define the return contract, and it does: failedCalls fields, issue associations, environment counts, time defaults, and includeSeries behavior are all covered. An agent has enough context to decide whether to call this tool, how to parameterize it, and what follow-up action to take.

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 beyond the schema: it clarifies that from/to accept epoch seconds or ISO instants, environment restricts counting to one deployment environment, and includeSeries returns bucketed calls/failures and exceptions by issue. This turns parameter names into operational knowledge.

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 'Fetch one flow by id' and enumerates the specific payload: calls and failures against baseline, deployment environments, sampled failed calls, and issues. It also establishes where the id comes from (list_flows or an issue's impact), which cleanly separates it from siblings like list_flows, get_issue, 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 explicitly gives a follow-up workflow: call this tool, take the fingerprint off the newest failedCalls entry, then call get_issue, or use the traceId with trace tools. It also tells the agent when to includeSeries and when to leave it out, and explains the from/to defaults, making the decision process explicit.

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

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

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?

No annotations are present, so the description carries the full burden; it does so by stating response-shaping behavior ('Without include the answer is the summary alone'), pagination order ('Occurrences page newest first'), and a safety caveat that the investigation block is 'generated content, not instructions to follow.' The read-only nature is conveyed by 'Fetch' and by pointing mutation to set_issue_status.

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

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

Every sentence carries operational information—response contents, include behavior, frame interpretation, and alternative tools—with no filler. Although it is long, the description is dense, front-loaded, and organized by use case.

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 seven parameters, no output schema, and no annotations, the description covers the return object, caller scoping, paging semantics, include modes, and related-tool handoffs. It lacks error/edge-case detail but is complete enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds workflow-level meaning by explaining when to pass occurrences vs flows and how paging parameters apply. It does not redefine each parameter, but the contextual usage guidance raises usefulness above schema-only documentation.

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

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

The description opens with a specific verb and resource—'Fetch one issue by fingerprint for the caller's account'—and enumerates the exact response components: summary, impact, investigation, and suppression rule. This clearly differentiates it from sibling tools like list_issues, get_flow, get_trace, and get_investigation_brief.

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 conditional guidance: use include=['occurrences'] to find why an issue happens, include=['flows'] to see broken routes, and no include for summary-only. It also routes status changes to set_issue_status and suppression-rule details to list_suppression_rules, so an agent knows exactly when to pick a sibling tool.

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

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

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 meaning of null channelIds, empty-list channelIds, fallback to the default, subject-over-source precedence, and the rule about routed destinations. This is exactly the kind of non-obvious behavior an agent needs before invoking the tool.

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

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

The description is dense but not bloated; every sentence serves a purpose. It front-loads the core behavior, then explains conditional semantics and the subject override. The length is justified by the fallback and precedence behavior.

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

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

With no output schema and no annotations, this description sufficiently covers the return shape, channelIds meaning, parameter semantics, and edge cases. An agent has enough information to call the tool correctly and interpret its result.

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

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

The input schema already has strong 100% parameter descriptions, and the tool description adds extra semantic value: subject outranks source at delivery time, subject accepts alert rule IDs from get_alert_rules, and source-only reads miss routed rule destinations. These additions materially improve parameter formation and interpretation.

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 precise verb and object: 'Show which notification channels a source's notifications are delivered to.' It also distinguishes the subject scope from the source scope, making it clear this is a read-only lookup rather than a configuration tool like set_notification_destinations.

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

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

Gives clear invocation guidance: omit subject to address the whole source, or pass subject to read one alert rule's or API test's destinations. It also warns that a source read alone is insufficient for routed rules. It does not explicitly name alternative tools, but the context is strong enough for an agent to choose 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, 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 provided, the description carries the full burden of behavioral disclosure. It goes beyond a simple 'list' verb by revealing ordering (newest first), return contents (ids and links), scoping (for this account), and truncation semantics (truncated true means more exist). This is robust transparency for a read-only list 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 with zero filler. The core purpose and ordering are front-loaded, followed by parameter guidance and truncation handling. Every sentence earns its place, making it easy for an agent to parse quickly.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers everything an agent needs: what it returns (ids and links), ordering, scoping, parameter usage, and truncation interpretation. There are no missing details that would prevent correct invocation or result interpretation.

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

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

The schema already fully covers the parameter (case-insensitive substring matching), so the baseline is 3. The description adds value by explaining why to use this parameter (to find a specific dashboard, not scan the full list) and its role in overcoming truncation, thus going beyond the schema's literal definition.

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 (List), the resource (dashboards for this account), the ordering (newest first), and the included attributes (ids and links). This immediate clarity distinguishes it from sibling tools like describe_dashboards or delete_dashboard without needing to open their schemas.

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

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

The description gives explicit guidance on when to use the titleContains parameter ('to find the one dashboard the user is describing instead of scanning the full list') and how to handle truncation ('narrow with titleContains to reach them'). It lacks explicit mention of alternative tools, but the context is clear enough for an agent to select this tool over siblings based on the resource being dashboards.

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 to cover safety or side effects, the description carries the full burden and does so well: it discloses time windows (21 days, 24 hours, 7 days), the failure definition (exceptions or 5xx), the status code representation, and that rows are ordered worst-first. This gives the agent a strong behavioral model before invoking.

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 contributes either operational semantics or navigation guidance, and the primary purpose is front-loaded. The middle sentence is syntactically overloaded, listing several correlated facts in one long clause, which costs some readability but not enough to drop below a 4.

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

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

There is no output schema, so the description compensates by explaining row contents, ordering, and the field to inspect. It covers the main decision an agent needs to make (call this vs get_flow) and relies on the schema for parameter details. Slightly more explicit output-field structure would push it to a 5, but it is complete enough for correct invocation.

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

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

The input schema already documents all four parameters with 100% coverage, including defaults for limit and environment, so the baseline applies. The description adds no parameter-specific meaning beyond the schema, though it does reference the output field callersHit7d, which is return-value guidance rather than parameter semantics.

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

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

States a specific verb and resource ('List the caller's flows'), defines what a flow is, and scopes the result to routes/jobs with traces in the last 21 days. It also distinguishes itself from the sibling get_flow by describing this as the aggregate overview and get_flow as the per-flow detail drilldown.

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 an explicit use case: 'To answer which routes are hurting callers, call this and read callersHit7d on each row.' It also names the alternative get_flow for seeing every issue behind one route, giving an agent clear routing guidance without needing to inspect sibling 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 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, the description carries the full behavioral burden and does so richly: it discloses that the default list excludes ignored and rule-suppressed issues, explains each suppression flag and their precedence (suppressedOnly wins over others), notes that each result flags hasInvestigation and carries impact metrics, and describes the CALLERS sort. No contradictions are present.

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 purpose but runs long and dense, often repeating parameter details already present in the schema (e.g., suppression flag semantics). It could be structured more crisply with bullets or separate sections, and several clauses duplicate schema text, reducing conciseness.

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

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

No output schema exists, so the description must explain return values; it does so by naming key result fields (hasInvestigation, impact, suppressedBy, firstSeen, status) and indicating next steps like calling get_issue. Combined with its filter/sort guidance, it is complete enough for an agent to call the tool correctly and interpret 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?

Schema description coverage is 100%, and the schema already contains detailed parameter guidance (e.g., precedence for suppressedOnly, environment semantics). The description adds value by clarifying the default list behavior (excludes ignored and suppressed) and offering concrete combinations for common questions, but much of the parameter-level detail is already in the schema, so it goes beyond baseline 3 but is not wholly additive.

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

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

States a specific verb ('List') and resource ('production issues for the caller's account') and immediately scopes the operation with filters and sorts. It also distinguishes itself from get_issue by noting that get_issue reads the investigation brief, so an agent can separate the two without opening schemas.

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

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

Explicitly answers common analytical questions: what is new (status=NEW or sort=LAST_SEEN+desc), what has been broken longest (sort=FIRST_SEEN+asc+open status), and warns that without a status the oldest issue may already be resolved. It also routes to alternatives like get_issue, set_issue_status, list_suppression_rules, and manage_suppression_rule for follow-up 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 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 burden. It discloses the read-only nature implicitly (it 'lists' rather than mutates), explains the negated=true semantics for conditions, and mentions that the answer is 'shown to the person as written,' which is a useful behavioral trait. However, it doesn't explicitly state that the tool makes no changes (read-only), which a readOnlyHint annotation would have 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 single-paragraph but dense with useful details. It opens with the core purpose and then provides examples of usage. It's slightly long for a parameterless tool, but every sentence adds functional value, so it earns a 4.

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 no parameters and no output schema, the description fully explains what the tool returns and how to interpret it, including edge cases like negated=true. It also covers the workflow context. There is no missing information an agent would need to call it correctly.

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

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

The tool has zero parameters, so the description adds no parameter semantics beyond the schema's implicit 'no arguments.' The score is based on the baseline of 4 for no parameters, but the description doesn't need to explain anything since there are no params. A 3 is more appropriate because the description focuses on output rather than input, but the output is rich and explained well.

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

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

The description states a specific verb (list) and resource (suppression rules), and provides detailed information about what each rule reports (coverage, operator, conditions, expression). It distinguishes itself from siblings like list_suppressions and manage_suppression_rule by focusing on the caller's account rules with coverage metrics.

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 call this tool first ('when asked why an issue is missing from a list or why a card never arrived') and routes to manage_suppression_rule for delete/update/add actions, including a preview-before-create workflow. This is excellent 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 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, the description carries the full burden, and it goes far beyond basic mutation: it explains that suppressed issues still record events, update/delete rearm issues and report rearmedIssues, preview is side-effect free, one-condition rules are normalized to match='all', ENVIRONMENT matches at issue level, and star-only values are refused. These details reveal edge-case behavior an agent would otherwise discover only through failures.

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 methodically organized by action workflow and matching semantics, with concrete examples. Every section contributes essential execution knowledge, so the length is justified; it earns a 4 rather than 5 because it is verbose enough that a purely token-conscious agent might need to parse carefully, but the structure is clear and 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 tool with no output schema and six parameters, the description covers all necessary operational context: precondition steps, parameter requirements per action, exact return metrics (issuesMatched, rearmedIssues), and edge cases like negation and empty values. An agent has enough information to execute every action correctly without external lookups.

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 meaning: it explains match operators, condition fields and values, wildcards, negation semantics, and the interaction of ENVIRONMENT conditions with issue-level matching. It also clarifies which parameters each action requires, such as id for update/delete and page for previews, enriching the schema far beyond its field descriptions.

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

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

The description opens with a specific multi-verb purpose 'Add, retarget, remove or dry-run one suppression rule of the caller's account, chosen by action,' naming both the resource and all supported actions. It clearly distinguishes itself from sibling read tools like list_suppression_rules and from single-issue silencing via set_issue_status, so an agent can select it without ambiguity.

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

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

The description gives explicit step-by-step workflows for create, update, delete, and preview, including when to call list_suppression_rules first to read existing rules or ids dove. It also tells agents when not to use this tool ('To silence a single issue... call set_issue_status with IGNORED') and names the alternative, satisfying the when/when-not requirement completely.

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 is exceptionally candid. It discloses per-metric-type output availability, intentionally omitted SUMMARY quantiles, silent step coarsening with the authoritative 'step' field, truncation behavior via truncatedRows, explorerUrl null cases, and silent degradation of invalid &agg values.

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 tightly structured, with the purpose front-loaded and each section earning its place: output shapes, parameter semantics, return fields, empty-bucket behavior, coarsening, and explorerUrl guidance. There is no filler or repetition of schema text.

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 a complex 8-parameter tool, the description covers the return object, per-metric-type output differences, window emptiness semantics, truncation, coarsening, and explorerUrl conditions. An agent has enough information to call the tool correctly and interpret ambiguous responses.

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?

Even though schema coverage is 100%, the description adds substantial meaning beyond the schema: step unit semantics and minimum, delta-sum and rate behavior for SUM, aggregation across ALL services, data-point vs resource attribute restrictions, key regex constraints, field-over-attribute precedence, and filter value safety. This is far more than a restatement of parameter names.

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

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

The opening line 'Query a metric time series' names a specific action and resource, and the metric-type breakdown makes clear it returns aggregated time-series buckets rather than raw logs, traces, or SQL results. This is distinguishable from siblings like run_sql, spans, and logs even without an explicit comparison.

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

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

The description gives strong operational usage details: metricName and service come from list_metrics, omitting service aggregates across all services, and step controls bucketing. It mentions run_sql once to explain SUMMARY quantiles are not queryable there, but it never explicitly says when to choose metrics over run_sql or other 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. It discloses duplicate-title refusal, structural validation, live SQL execution, empty-panel and dead-series reporting, and the distinction between blocking errors and non-blocking warnings.

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

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

The description is long but dense with actionable guidance; most sentences earn their place by explaining behavior, failure modes, or workflow context. It is not perfectly front-loaded since it opens with workflow instructions rather than a crisp one-line purpose, but the structure remains effective for agent use.

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 covers prerequisites, validation behavior, failure semantics, duplicate prevention, link stability, and handover guidance, leaving little ambiguity about what the tool does and how to use 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 baseline is 3. The description adds context about definitionJson requiring a valid dashboard definition and that SQL will be executed, but it does not meaningfully expand on range or refresh beyond what the schema already documents.

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: 'Validate, ground, store, and mint a Fixter dashboard link,' which is a specific verb+resource pairing. It distinguishes this minting operation from update_dashboard and delete_dashboard by emphasizing creation plus validation.

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

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

The description gives explicit when-to-use guidance: check list_dashboards first, use get_dashboard on close matches, and update_dashboard instead of creating a duplicate. It also directs the agent to call describe_dashboards before first use and to compose with run_sql first, clearly defining the tool as a verifier rather than a designer.

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 and no output schema, the description carries the full behavioral burden and handles it thoroughly: never persists, never throws, structured fields ignored when fromQuerySql is set, anomaly backtest is null, and warnings[] never blocks saving. It also details rejection behavior and the FIELD_NEVER_OBSERVED signal.

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 sentence adds operational value, and it is front-loaded with the core purpose, then usage guidance, then parameter modes and return semantics. Despite its length, there is 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 21-parameter, no-output-schema tool, this is exceptionally complete. It documents the full return surface—normalizedSpec, problems[], backtest, seasonality, warnings[]—including dataCoverage statuses and how to interpret NO_MATCHING_DATA vs EVALUATED. Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema coverage is 100%, but the description still adds crucial semantics: the mutual exclusivity of fromQuerySql vs structured fields, groupBy plain-name restrictions, derivedGroupBy expression/label requirements, static vs anomaly condition modes, and clamping/defaulting behavior for lookbackDays and windowMinutes. This goes far beyond the baseline.

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

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

The description names a specific verb ('validates and normalizes') and resource ('a candidate rule spec') and immediately frames it as the 'preview→save gateway', distinguishing it from sibling save_alert_rule. It also states the read-only nature and that it never persists or throws.

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 'Call this before save_alert_rule to calibrate' and explains how to interpret backtest results before adjusting thresholds. It also tells the agent to fix problems[] before saving, and that save_alert_rule re-runs the same validation, making the usage workflow 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?

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?

No annotations are provided, so the description must carry the full burden, and it does comprehensively. It discloses read-only behavior, specific SQL limitations, default 7-day time bounds, zero-filling for bucketed queries, DISTINCT semantics, metrics aggregation caveats, and return-field behaviors such as truncatedRows and priorWindow conditions. Nothing is left undisclosed.

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 long, the description is meticulously organized with clear sections (sources, common fields, functions, limitations, time bounds, tool routing, examples, return fields). Every sentence serves a purpose for a complex SQL dialect; there is no fluff or redundant restating of the schema. The structure makes it easy to navigate 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?

With no output schema and no annotations, the description is fully self-sufficient. It defines all return fields (rows, queryStats, explorerUrl, priorWindow, truncatedRows), explains zero-fill and truncation behavior, burn-rate formulas, and metric aggregation patterns. An agent can invoke the tool correctly without needing external documentation.

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

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

Schema coverage is 100%, but the description adds far beyond the schema. For the sql parameter it documents the full QuerySQL dialect, custom functions, examples, and edge cases. It also explains maxChars handling (rows dropped from the end) and compareWithPriorWindow requirements (literal timestamp bounds, error otherwise). Every parameter is meaningfully enriched.

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 action and scope: 'Execute a read-only QuerySQL SELECT against the observability data.' It then explicitly differentiates from sibling tools in the 'Prefer purpose-built tools' paragraph, naming correlate, get_trace, and aggregate_spans as alternatives for specific use cases. An agent can immediately tell what this tool does and how it differs from 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 when-to-use versus alternatives: 'Use run_sql for ad-hoc analysis that the other tools don't cover' and lists when to use correlate, get_trace, and aggregate_spans instead. It also includes limitations that define what to avoid (no writes, no UNION, no CROSS JOIN) and the 7-day time-bound constraint, giving complete selection 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 bears full responsibility for behavioral disclosure, and it excels. It warns that update is a whole-object replace, not a merge, and lists the specific carve-outs for status and delivery. It details re-validation behavior, the difference between warnings and problems (with a concrete warning code FIELD_NEVER_OBSERVED), and how to interpret dataCoverage. It even explains edge cases like groupBy expression rejection and derivedGroupBy label semantics. This transparency is exceptional.

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 26 parameters. It front-loads the most critical behavioral warning (whole-object replace) in the first paragraph. The use of section headers (METRIC RULE, ANOMALY METRIC, Common fields) and bullet-like indentation keeps it scannable. Every sentence provides actionable information; there's no fluff or redundancy. It's structured to maximize comprehension for a complex tool.

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

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

Despite no output schema, the description covers the response semantics well: it mentions problems[] and warnings[], states that problems[] populates instead of rule on validation failure, and clarifies that warnings are advisory and never block saving. It also gives guidance on actionable next steps (fix spelling, re-preview). The description fully equips an agent to call, interpret, and troubleshoot. No critical gaps are apparent.

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?

Even though schema coverage is 100%, the description adds substantial semantic value beyond the schema. It explains relationships (expression vs fn), conditional requirements (metricName/metricType only for METRICS), format constraints (groupBy field names only), and the meaning of labels in derivedGroupBy. It clarifies defaults (notifyOnResolve, warningConsecutiveWindows), and warns about common pitfalls (don't divide by 100 again). This far exceeds the baseline for fully-covered schemas.

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 core function: 'Create or update an alert rule for the calling tenant in one call.' It also distinguishes between metric and anomaly rules, and explicitly notes limitations ('Compound multi-condition rules can't be created here'). It differentiates itself from siblings like set_alert_rule_status and set_notification_destinations by carving out those concerns, which makes the purpose unmistakable.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it names preview_alert_rule for validation and calibration, set_alert_rule_status for status changes, set_notification_destinations for delivery routing, and the web editor for compound rules. It also provides concrete directives like 'use fn instead unless you need a custom ratio' and 'omit it to let the server infer the unit.' This is exemplary 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 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 provided, the description fully discloses behavioral traits: RESOLVED causes future events to reopen as REGRESSED and send a regression card; IGNORED keeps counting events but suppresses notifications and default-list appearance; ONGOING reopens. It also discloses partial-failure semantics: each fingerprint returns an outcome such as NOT_FOUND or ERROR, and remaining issues are still set. This goes well beyond what the schema or annotations reveal.

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

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

The description is long but dense and every sentence serves a purpose. It front-loads the core operation and then layers status-specific behavior, constraints, failure semantics, and the relevant alternative. There is no filler or redundant restatement of the tool name.

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

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

For a mutation tool with no annotations and no output schema, this description is exceptionally complete. It covers purpose, the meaning and consequences of each status, fingerprint limits, partial-failure behavior, return outcomes, and the alternative tool for broader suppression. An agent has everything needed to select and invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics beyond the schema: it explains what each status value means behaviorally, clarifies that fingerprints come specifically from list_issues, and notes the same status is applied to all supplied issues. It also clarifies the outcome format for each fingerprint, which helps the agent interpret responses even though there is no output schema.

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

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

The description uses a specific verb and resource: 'Set the same status on one or more issues of the caller's account, by fingerprint from list_issues.' It clearly differentiates this tool from related tools like manage_suppression_rule by explicitly listing what it operates on (named issues) and what it is not for (service/environment/exception-type level suppression).

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 use-case guidance for each status value (RESOLVED, IGNORED, ONGOING) and names the exact alternative tool and action for suppression at a broader scope: 'call manage_suppression_rule with action=create.' It also addresses list-length limits by directing callers to split longer lists. This is strong when-to-use vs. alternative 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 full burden and does it well. It discloses mutation behavior, fallback resolution to subject/source/default, the distinction between omit vs empty list, precedence between subject and source rows, and the return format. This level of behavioral detail is unusually high 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?

The description is dense but every sentence teaches a distinct behavior needed for correct invocation: ADMIN scope, UUID source, omit vs empty, subject routing, and output. It eschews filler and stays organized in two coherent paragraphs.

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 three parameters, no annotations, and no output schema. The description nevertheless explains what the input values mean, what happens for each input variant, the precedence behavior, and the return value. It fully compensates for the missing structured annotations and 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?

While the schema already provides 100% coverage, the description enriches each parameter with operational meaning beyond schema strings: it clarifies that channelIds must come from list_alert_channels, defines the fallback semantics of 'omit', the disabling semantics of '[]', and the subject's dual role as an alert rule id or API test id. This goes well beyond the standard 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 states a specific verb ('Choose/set') and resource ('which notification channels a source's notifications are delivered to') and clearly conveys that this is the mutation counterpart to get_notification_destinations. It also notes the ADMIN-only restriction, which locks the operational scope for the agent.

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

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

The description gives clear usage instructions: pass channel UUIDs from list_alert_channels, omit to clear, pass [] to disable, and use subject to route a single rule/test. It also provides a delivery-order caveat, but it does not explicitly refer to get_notification_destinations as the way to read current destinations. Since the setter role makes the usage context clear and alternatives are not necessary, this is strong but not fully explicit.

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

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

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.