Fixter

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

Annotations already declare idempotentHint=true and destructiveHint=true; the description adds meaningful context beyond them — the ADMIN requirement, the nuance that a repeat add is a no-op unless `sources` is supplied (which overwrites existing sources), and the shape of the return. It does not spell out the full destructive scope, but it discloses the overwrite risk that justifies the destructive hint.

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

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

Three dense sentences with no filler, and the core action plus permission gate are front-loaded. The final sentence is long and packs several clauses, but every clause carries operational information the agent needs.

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

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

With no output schema, the description compensates by describing the JSON return and the significance of its `id`, plus auth, idempotency, and downstream consumption. Nothing needed to invoke the tool correctly is missing.

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

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

Schema coverage is 100%, so the schema documents both parameters and the baseline would be 3. The description earns above baseline by flagging the critical distinction between the returned registry UUID `id` and the input `channelId`, warning the agent not to substitute one for the other downstream.

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 ('Add a Slack channel id to the authenticated customer's notification-channel list') and scopes it to the authenticated customer. It is clearly distinguishable from siblings like list_alert_channels and remove_alert_channel without opening a schema.

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

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

Gives the ADMIN-only precondition and explains the idempotent behavior, and it routes the agent onward by noting the returned UUID must be passed into save_alert_rule / set_alert_rule_delivery rather than channelId. It stops short of naming an explicit alternative or a when-not-to-use condition, so it is clear context rather than full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds substantial behavior beyond them: default reads a pre-aggregated rollup with minute resolution for 45 days and hourly up to 400 days, parent breakdown is computed on demand over raw spans (a real cost) and needs scoping, and truncation is surfaced via truncatedRows/truncationHint. It also documents the empty-bucket behavior for a series that stopped.

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

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

Front-loads the purpose and the 'START HERE' routing before any detail, and organizes the rest into labeled sections (Parent breakdown, Params, Returns) that an agent can skim. It is on the long side for a read tool, and the Returns paragraph partly duplicates schema-described fields, but almost every clause carries usable 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?

There is no output schema, yet the description fully specifies the return shape (buckets[] with group, spanCount/okCount/errorCount/unsetCount, errorRate 0-100, throughputPerSecond, durations, quantileNanos, queryStats) plus truncation and empty-bucket semantics. Combined with resolution limits and drill-down guidance, nothing needed to call or interpret the 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%, so the baseline is 3, but the description adds genuine meaning: it explains what groupBy actually does, and specifically that adding parent_operation splits an operation by its immediate caller with a concrete '8% overall vs 92% under one caller' example. The step units and defaults are largely repeated from the schema, keeping it short of a 5.

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

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

Opens with a specific verb+resource+output contract: 'Aggregate spans into RED metrics: request count, error rate, throughput, and latency percentiles (p50/p90/p95/p99)'. It explicitly distinguishes itself from siblings spans/get_trace as the starting point, and from metric-style tools by naming the concrete outputs an agent will get.

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?

States explicit triggering questions ('where are errors / latency concentrated?', 'what changed between two windows?') and then names the alternative path: drill into raw spans via spans/get_trace once pointed at a specific (service, operation). It also gives a when-to-use caveat for the expensive parent breakdown ('keep it scoped: pass a tight from/to and a service/name filter').

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

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

Annotations already cover readOnly/idempotent/non-destructive, so the description does not need to restate safety. It adds real undisclosed behavior instead: how the scan window is derived (earliest span -5s / latest end +5s), that exemplar filtering is window-bounded while log filtering is not, and the 1000-row truncation flags. It stops short of describing cost/latency traits for the expensive verbose path, which keeps it off a 5.

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

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

Front-loaded with the one-line purpose, then a field block, then behavioral notes — the structure lets an agent skim. It loses a point for the closing 'Returns:' list, which restates the field enumeration already given at the top and bloats the definition noticeably.

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 carries the full return burden and does it: every returned field is named, truncation semantics are given per array, the empty-result edge case (unknown trace still returns tagged logs) is spelled out, and traceUrl usage guidance tells the agent what to do with evidence.

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

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

Schema coverage is 100%, so baseline is 3; the description earns above that by explaining what verbose actually changes (flattens attributes for spans and logs, adds a resource object, caps strings) and by advising verbose=false first with maxStringChars to tighten truncation per call. Marginal rather than decisive: the 4000-character ceiling lives in the schema, not here.

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

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

States a specific verb and resource ('one-shot cross-signal pivot for a trace id') and immediately enumerates exactly what comes back — trace summary, spans, logs, exemplars, window. An agent can distinguish this from get_trace, spans, logs and run_sql without opening any schema.

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

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

Explicitly names itself as 'the primary entry point when you have a trace id', then gives named alternatives with the conditions that select them: run_sql for raw columns, logs with traceId + level for cheaper error triage, and the drill-down tools after reviewing. That is when/when-not/alternatives in one place.

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

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

Goes well beyond the annotations: reveals the dry-run trial executed before saving (one attempt, no retries), that nothing is persisted on failure and the call should be fixed rather than retried, that private/loopback/cloud-internal URLs are refused, and that a successful create returns the test with id, state and a trialRun. The non-idempotent, open-world annotation profile is consistent with this text.

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

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

Front-loads the definition, then type dispatch, then variables, then return and trial-run semantics — each sentence carries distinct operational value. It is long, but length is driven by a 28-parameter tool and none of the paragraphs are 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 28-parameter mutation tool with no output schema, the description still tells the agent what comes back (created test with id and state, plus trialRun) and what failure looks like. The one substantive hole is that it describes the parameter surface using two names that are not in the schema, so an agent must reconcile the text against the schema to configure type-specific fields 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 already 100%, so baseline is 3; the description adds real value by explaining the type dispatch between HTTP and MCP parameter groups, the full Postman-style variable syntax with escape rules, and the ADMIN-only scope of channelIds. That lift is partially offset by referring to nonexistent parameter names (httpTarget, mcpTarget) which could confuse an agent mapping description text back to the schema.

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

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

Opens with a specific verb and resource ('Define an API test') and immediately defines the concept: a scheduled test of a production HTTP endpoint or MCP server with request + assertions executed on an interval. An agent can distinguish this from list_api_tests, get_api_test, update_api_test and detect_mcp_protocol without opening any schema.

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

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

Gives explicit routing guidance: 'Use this to start watching an HTTP endpoint or an MCP server', then branches on type="HTTP" vs type="MCP" and points to detect_mcp_protocol as a prerequisite for MCP servers. However, it names 'httpTarget/mcpTarget' params that do not exist in the schema (they are httpUrl/mcpUrl), and it never states when to prefer update_api_test over create.

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

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

Annotations cover the safety/state profile (non-read-only, non-idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: the secret is write-only and the response returns only id, name and type. It does not warn that retries create duplicate credentials, but the key lifecycle disclosure is 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?

Front-loaded with purpose, then the type-to-fields mapping, then the return contract. Dense but every clause carries information; only minor compression is possible.

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 supplies the return contract (id, name, type) and how the id is consumed by API tests. For a 12-parameter tool with nested objects and conditional requirements, all the critical call-shaping information 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 coverage is 100%, so the baseline is 3. The description exceeds it by aggregating the per-type conditional requirements (BASIC=username+password, BEARER=token, OAUTH2=tokenUrl+clientId+clientSecret) and stating the constraint that API_KEY needs at least one entry across apiKeyHeaders/apiKeyQueryParams — a rule not present in the schema.

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

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

States a specific verb and resource: 'Store a reusable auth credential that API tests can use to reach a protected endpoint.' This distinguishes it clearly from sibling create_api_test and from unrelated create_* 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?

Gives clear context for when to use it — provisioning a credential an API test will reference via httpCredentialId/mcpCredentialId. It does not name alternatives (e.g., list_api_test_credentials to reuse an existing one, delete_api_test_credential), so exclusions are absent.

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

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

Adds substantial behavioral context beyond the annotations: WRITE operation requiring the ADMIN role, the fact that it alters burn evaluation data rather than muting notifications, per-signal scoping, and duration/expiry semantics. Annotations already cover non-destructive/non-idempotent status, and the description complements them without contradiction.

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

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

The description is front-loaded with the core purpose and alternative tool, then organized under Scope and Duration headings. It is longer than necessary because some parameter details repeat the schema descriptions, but the structure keeps the reader oriented and most sentences earn their 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 complex write tool with no output schema, the description covers permissions, effect on evaluation, scope rules, normalization behavior, and expiry defaults. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful cross-parameter constraints such as operation being required for LATENCY_P95 and signal scope limitations (THROUGHPUT has no burn evaluation). It also explains URL_PATH normalization with a template example beyond the schema wording.

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 ('create_ignore_rule') and precisely defines what an ignore rule does: exclude a traffic fingerprint from burn-rate evaluation. It distinguishes the tool from sibling alternatives such as suppress_signal and clearly describes the effect (changes evaluation data, not notifications).

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 names the alternative for notification-only silencing ('use suppress_signal instead') and explains the condition that selects it. It also gives concrete usage context including UI button creation, default expiry, and scope constraints for LATENCY_P95 versus ERROR_RATE.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is covered. The description adds real value on top: 'Permanently' signals irreversibility and the 'WRITE: available to any authenticated user' note states the auth requirement, which annotations do not capture.

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 very short sentences, with the destructive action front-loaded and the authorization note second. Every clause carries information; nothing is padded or repeated from the title.

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

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

For a one-parameter destructive tool with no output schema and annotations covering idempotency and destructiveness, the permanence and auth notes make it largely complete. It stops short of describing what happens to dependent alert destinations or the response on an unknown rule id.

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 ruleId parameter is fully documented as a UUID in the schema. The description adds no format, sourcing, or lookup guidance beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Permanently delete') and resource ('an alert rule'), which separates it from the sibling deletes (delete_dashboard, delete_api_test, delete_ignore_rule) without opening any schema. An agent can identify the target resource unambiguously.

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 notes the authorization scope ('available to any authenticated user') but gives no when-to-use guidance, no prerequisites, and no alternatives. Notably, siblings like set_alert_rule_status could disable a rule rather than delete it, and delete_alert_rule never mentions this trade-off.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description still adds value by spelling out irreversibility ('cannot be undone') and the scheduling side effect, though it says nothing about auth requirements or failure modes.

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

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

Two compact sentences with no filler; the destructive consequence is front-loaded and the alternative is offered immediately after, which is exactly the order an agent needs.

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

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

For a single-parameter destructive delete with no output schema and full annotation coverage, nothing material is missing: the effect, irreversibility, and the sibling alternative are all stated.

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?

Only one parameter and schema description coverage is 100%, so the schema already documents apiTestId fully. The description adds no format, origin, or lookup detail beyond it; baseline 3 applies when the schema carries the 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 plus a second effect ('stop scheduling it'), which goes beyond the name. It explicitly distinguishes itself from the closest sibling (disable_api_test), so an agent can choose correctly without opening either schema.

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

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

The description names the alternative (disable_api_test) and the exact condition under which it should be preferred ('only want to pause it temporarily'). That is explicit when-to-use routing rather than implied guidance.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so safety and repeatability are covered structurally. The description adds a concrete failure mode not present in the annotations: referential-integrity blocking until dependent API tests are reassigned or removed. Auth requirements and confirmation needs are still unstated.

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

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

Two tight sentences: the action first, then the blocking condition. No filler, and the constraint is front-loaded rather than buried.

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?

A destructive one-param tool with no output schema and full annotation coverage needs little more; the failure precondition is the essential missing piece and it is supplied. Only the origin of a valid credentialId is left implicit.

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?

Only one parameter with 100% schema description coverage, so the schema already documents credentialId fully. The description's 'by id' adds no format, sourcing, or validation detail beyond that, which is the expected baseline when the schema does the work.

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 (delete) and resource (stored API test credential) with the keying field (id). Combined with the name, an agent can distinguish this from create_api_test_credential and list_api_test_credentials without opening any schema.

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

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

Gives an explicit precondition: it fails while any API test still references the credential, and instructs the caller to reassign or delete those tests first. It does not, however, point at the sibling that surfaces deletable credentials (list_api_test_credentials) or state when deletion is unnecessary.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds consequences the annotations cannot express - the share link stops working for everyone, and removal is permanent - which is meaningful context for an irreversible action.

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

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

Three short sentences, zero waste, and the destructive consequence is front-loaded. The consent constraint is placed last, which is the right position for a caveat.

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

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

For a single-parameter, outputless delete, the description covers purpose, irreversibility, and consent requirements. It does not mention whether the operation errors when the id is missing/unknown, but nothing essential to correct invocation is absent.

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?

Only one parameter and schema description coverage is 100%, so the schema fully documents 'id'. The description adds nothing about the identifier (format, source, where to obtain it), which is acceptable at this coverage level but earns no surplus.

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 ('Permanently remove a stored dashboard'), which clearly separates it from siblings like update_dashboard, get_dashboard, and mint_dashboard. The word 'Permanently' also signals destructive 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?

Gives explicit when-to-use guidance ('Only call this when the user has asked for the dashboard to be removed'), which functions as a consent guardrail. It does not name alternative siblings (e.g., update_dashboard for edits), so it stops short of full when/when-not routing.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=true, so the safety profile is covered. The description adds beyond the structured data by flagging 'WRITE: requires the ADMIN role,' an authorization prerequisite not encoded anywhere else, though it says nothing about reversibility or failure behavior.

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

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

Two short sentences: the effect first, the operational constraint second. Every clause earns its place with no filler or restatement of the title.

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

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

For a one-parameter delete with full schema coverage and annotations carrying the destructive/idempotent profile, the description covers what matters: the semantic effect of removal and the ADMIN requirement. No output schema exists and none is implied, so remaining omissions (error cases, confirmation flow) are minor.

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

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

Schema coverage is 100% for the single id parameter, and its schema description already explains format (UUID) and provenance (from create_ignore_rule or list_ignore_rules). The description contributes nothing further about the parameter, so the baseline 3 applies.

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

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

States a specific verb (Remove) and resource (ignore rule) and, unusually, the functional consequence: the fingerprint counts toward burn-rate alerts again. That lets an agent distinguish it from create_ignore_rule/list_ignore_rules and sibling deletes like delete_alert_rule without opening a schema.

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

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

The stated effect implies the usage context (undo a suppression so alerting resumes), but there are no explicit when-to-use/when-not conditions and no named alternatives such as list_ignore_rules for finding the id or suppress_signal for temporary suppression. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, and the description adds auth scope ('READ: available to any authenticated user') plus the important determinism trait ('reads no telemetry and returns the same answer for every caller'). That is real behavioral context beyond the structured hints.

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

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

Front-loaded with the core definition and kept to a few dense sentences, each carrying information. The parenthetical nesting (per source ... each with ...) makes the opening slightly heavy, but no sentence is wasted.

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 carry the return-shape burden, and it does describe the payload (functions per source, unit, defaultMode) reasonably well. It stops short of describing the exact nesting/format of the response, which is the only real gap for a zero-param catalog 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?

Zero parameters, so the baseline is 4; there is nothing for the description to clarify. It does name the source enum values (LOGS, SPANS, METRICS) and the THRESHOLD/ANOMALY modes, but those describe the return payload rather than inputs.

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 resource (static measure catalog for authoring alert rules) and its exact contents (measure functions per source with unit and defaultMode). It explicitly differentiates itself from describe_schema, which the agent could otherwise confuse it with.

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 sequencing ('Call query's describe_schema first ...'), an explicit scope limiter ('Use this tool only to pick a measure once you know the source and, for METRICS, the metric's kind'), and notes what this tool no longer returns. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world, so the safety profile is covered without the text. The description adds real value by disclosing the exact subject matter and the 'call once' lifecycle, but says nothing about the returned form (prose vs. structured document) or size, which matters for a zero-argument guide tool an agent must consume.

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 purpose is front-loaded, the topic enumeration follows, and the call instruction is last where an agent will read it before acting. The content list is long but every item is distinct information the guide actually contains, so nothing is 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?

With zero parameters, no output schema, and rich annotations, the description carries the burden of telling the agent what it will learn – and it does so item by item, which functions as a table of contents for the return value. The only gap is that it does not characterize the response format, a minor omission for a static guide 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 takes no parameters, so there is no parameter semantics to explain and the baseline of 4 applies. The description correctly avoids inventing or implying any arguments.

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?

Names a specific verb and resource (a complete guide to composing a Fixter dashboard) and enumerates its exact contents: definition format, panel kinds, chart-form selection, grid layout, units, environment scoping, and mint_dashboard validation. That enumeration makes it unmistakably a documentation tool rather than a reader like get_dashboard or a writer like mint_dashboard, though it never explicitly contrasts itself with those siblings.

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

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

The closing sentence gives explicit, actionable timing: 'Call this once before composing your first dashboard in a conversation' – it states both when (before composing) and the cadence (once), which implicitly forbids repeated calls. It stops short of naming alternatives for the reuse case, so it is strong but not fully complete on when-not.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description goes further by disclosing return shape (per-field type/coverage/top values/GROUP BY verdict), measure metadata, function argument counts, and that the metrics list is default-bounded with metricsMatched reporting the true total. It does not mention auth or rate limits, but adds substantial context beyond the annotations.

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

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

Front-loaded with purpose and the before-run_sql rule, then organized into scannable blocks. It is long, and the filter semantics are restated from the schema, but nearly every sentence carries usable detail.

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

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

No output schema exists, so the description carries the full burden of explaining returns — and it does: field profiles, measures with defaultMode, QuerySQL functions, and metrics pagination totals. An agent has everything needed to call it 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%, so the baseline is 3, but the description adds real meaning beyond the schema: source defaults to logs, service drills into per-service dynamic attributes, prefix exists specifically to reach past the default-bounded metric page, and filter is a QuerySQL predicate sharing run_sql field names with no subqueries allowed. Only 'path' lacks description-level elaboration.

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: 'Discover the queryable fields, functions, and measures for a data source.' It also scopes the sources (logs, spans, metrics) and clearly separates itself from run_sql, which it feeds.

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 sequencing guidance: 'Use this before run_sql to learn what's available,' plus a concrete workflow (call with no arguments to get services, then drill in with service=<name>). It also states the metrics-specific escape hatch via prefix, which is a when-to-use condition.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds what annotations cannot: it discloses that up to seven requests are made on the customer's behalf. It also defines all four outcome values and what data is returned for failed revisions (status, content type, first bytes).

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

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

Front-loads the probe action and revision list, then follows with outcomes and the create_api_test linkage — good ordering with no filler. It is dense to the point of being a single long block, which slightly hurts scanability.

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

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

There is no output schema, so the description carries the burden of describing return values, which it does thoroughly via the enumerated outcomes and per-revision failure details. An agent has everything needed to call it and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains when mcpCredentialId matters (servers that refuse with 401/403) and ties it to list_api_test_credentials-adjacent workflow. Minor missed opportunity to state that the probe is unconditional across all revisions regardless of params.

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 ('Probe a remote MCP server') and enumerates the exact protocol revisions covered, so an agent knows precisely what is being tested. It is clearly distinguishable from siblings like create_api_test, which it explicitly precedes.

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 says 'Use this before create_api_test to choose mcpProtocolRevision' and explains the three downstream choices (ANY, NEWEST_SUPPORTED, dated revision). It also gives conditional next steps per outcome, e.g. passing a credential or falling back to ANY when AUTH_REQUIRED is returned.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description goes beyond them by naming the resulting state (PAUSED), stating that no new runs are recorded, and clarifying the change is reversible via enable_api_test — useful for judging the 'destructive' hint. It does not describe error behavior or permission 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?

Three compact sentences, front-loaded with the action and its immediate effect. Every sentence adds a distinct fact (what it does, the state change and persistence, the return value) with no repetition of the tool name or title.

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

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

For a single-parameter state-toggle with no output schema, the description covers the effect, reversibility, and return value, and annotations cover idempotency and destructiveness. Missing only failure/permission behavior (e.g., unknown id, already-paused test), which is a minor gap given the idempotent hint.

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

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

With 100% schema description coverage and a single required apiTestId parameter, the schema already carries full parameter semantics ('Id of the API test to disable'). The description adds no format, sourcing, or lookup guidance beyond that, 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?

States a specific verb (Disable), clarifies it means pause, names the exact resource (an API test), and describes the resulting effect (stops running on its schedule, state becomes PAUSED). This distinguishes it from enable_api_test, delete_api_test, and update_api_test without needing to open any schema.

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

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

Gives clear context: use this to stop a test from running on its schedule, and notes the reverse path via enable_api_test. It implies a contrast with delete_api_test (pause vs. permanent removal) but never states that alternative explicitly, nor any precondition such as the test already existing or being enabled.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and non-idempotence, so the bar is lower, yet the description still adds real value: it says the test resumes on its interval and its state resets to UP, and that it returns the updated test (useful given no output schema). It does not say what happens if the test is already enabled or what errors occur.

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

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

Two tight sentences with zero waste: the action is front-loaded, followed by the state effect and return value. Nothing redundant.

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

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

For a one-parameter state-toggle mutation with no output schema, the description covers the action, the resulting scheduling behavior, the state transition to UP, and the return value. Only edge-case behavior (already-enabled test, auth requirements) 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% with a single well-documented apiTestId parameter, so the schema carries the burden. The description adds no syntax, format, or lookup guidance beyond 'a paused API test', which is the expected 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?

States a specific verb+resource ('Enable ... a paused API test') and clarifies the mechanism ('resume scheduling'), which keeps it distinct from create_api_test and update_api_test. It never names the obvious counterpart disable_api_test to sharpen the contrast, so it falls short of full sibling differentiation.

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

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

The phrase 'a paused API test' implies the precondition for use, but there is no explicit when-to-use/when-not guidance and no mention of disable_api_test or other state-management siblings. Usage is inferable rather than stated.

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

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

Annotations only mark this as a destructive, open-world, idempotent write; the description carries far more: the operation is asynchronous (RUNNING can take half an hour), the outcome is surfaced later on get_issue's fix block, retries only re-push the pull request rather than re-doing work, and nothing is ever merged. The full status taxonomy (INELIGIBLE, BUSY, PR_OPENED, FAILED, UNAVAILABLE, DISABLED, etc.) with per-case recovery makes the behavior predictable in a way no annotation could.

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

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

Front-loaded correctly: what it does, then the order of operations, then the result semantics. Every clause carries recovery information, but it is delivered as one unbroken wall of text with a status-code dump that would be far more scannable as a short list.

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 must explain returns — and it does, covering both the immediate answer and the deferred fix block on get_issue. Given an async mutation with a rich failure taxonomy and only two parameters, nothing an agent needs in order to call it, interpret it, or recover from an error is missing.

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

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

Schema coverage is 100%, so both parameters are already documented; the description only adds provenance for the fingerprint (it comes from the investigation block via get_issue/list_issues). The optional hint parameter is never mentioned in the description at all, so the schema does the remaining work. 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?

States a specific verb and resource ("open a draft pull request that fixes one issue") plus scope (caller's account, customer's own repository). It is unambiguously distinguishable from siblings like get_issue, list_issues, and start_investigation, which it names explicitly.

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

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

Gives an explicit prerequisite chain: list_issues to pick an eligible issue, get_issue to read the investigation block, and only then fix_issue with a code-verified root cause. It also routes to the alternative tool (start_investigation) for the NO_BRIEF case and tells the agent when NOT to call (ISSUE_NOT_OPEN, NOT_AN_ISSUE).

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

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

Annotations already cover readOnly/idempotent safety, but the description adds substantial semantic behavior: channelIds can be empty (alerts off), null (inherits tenant default), and rule-level routing outranks the default. This is genuinely useful context beyond annotations.

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

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

Front-loaded with the resource and READ permission info, followed by structured routing guidance. Slightly dense but every sentence carries operational meaning.

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

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

No output schema, yet the description fully explains the shape of entries (channelIds semantics) and points to sibling tools for name resolution and default comparison. Complete for an agent to call 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% and the ruleId description already says 'omit to list every rule'. The description reinforces this and adds semantics about what each entry contains, though the parameter itself is well covered by 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?

Precise verb+resource: states it returns where the calling tenant's alert rules deliver alerts, and the read-only scoping is clear. Distinguishable from siblings like set_alert_rule_destinations and get_notification_destinations by focusing on per-rule routing.

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

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

Explicitly states 'Supply ruleId for one rule; omit it to list every rule', and routes agents to the appropriate sibling tools for resolving channel names and reading the tenant default. Clear when and how 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds context they do not carry: the access requirement ('available to any authenticated user') and the exact shape of the returned payload (source, filter, measure, groupBy, compiledQuerySql, condition), which matters because there is no output schema. It also discloses a scope limitation (no destination data) rather than letting the agent assume.

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

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

Three short paragraphs, front-loaded with the operation, then the parameter behavior, then the routing caveat. No sentence is redundant and the scope warning is placed where it is needed.

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 no output schema, the description covers the access model, both call modes, the returned field set, and the adjacent tools for the destination question. Nothing an agent needs in order to call it correctly, or to avoid misusing it, is missing.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Optional rule id (UUID); omit to list every rule'. The description restates the same omit/supply semantics without adding format or validation detail, so the schema is doing the work — baseline 3 applies.

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

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

States a specific verb and resource ('Fetch the calling tenant's alert rules') and explicitly covers both modes: list-all when ruleId is omitted, single-rule fetch when supplied. It also names the siblings it is not (get_alert_rule_destinations / set_alert_rule_destinations), so an agent can route without opening any schema.

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

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

Gives an explicit conditional for the single parameter (omit to list, supply to fetch one) and states the boundary case that would otherwise cause a wrong tool choice — that destinations are not returned here — then names the exact alternatives for reading and writing destinations. This is when/when-not/alternatives in full.

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

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

Annotations already cover readOnly/idempotent/non-destructive, yet the description adds real domain semantics: the four possible health states, what RATE_LIMITED actually means (HTTP 429, fix on the customer side), and that currentRevision is null until the first run for MCP tests. It does not cover error behavior for an unknown id, which is the main remaining gap.

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

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

Front-loaded with the core action and scope, then the semantic carve-outs. Every sentence carries information, though the RATE_LIMITED explanation is longer and more awkwardly wrapped than needed for a single-record fetch.

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 does the work of explaining what comes back: full configuration, health state, and consecutive-failure count. It stops short of describing the shape of 'full configuration', but an agent has enough to call it correctly.

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

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

One parameter at 100% schema description coverage, so the schema already explains apiTestId. The description adds no id format, provenance, or example beyond what the schema states — baseline 3 applies.

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

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

States a specific verb ('Fetch'), resource ('API test'), and scope ('a single ... by id'), plus enumerates the returned fields. This clearly separates it from list_api_tests (plural listing) and from get_api_test_runs/get_api_test_destinations (different sub-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?

Usage is implied by the 'by id' framing — an agent knows it needs an id, presumably from list_api_tests — but there is no explicit when-to-use, no named alternative, and no stated preconditions. Adequate but leaves routing to inference.

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

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

Annotations already establish readOnly/idempotent/non-destructive, yet the description adds substantive behavior: auth requirements ('Any role may read'), the precise return shape for each mode, and the critical null-vs-empty-list semantics plus per-test-over-source precedence. These are non-obvious traits the agent could not infer from structured fields.

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

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

Front-loaded with the core verb and auth note, then splits cleanly into the with-id and without-id cases. It is slightly repetitive, restating the inheritance/empty-list semantics in both blocks, but every sentence still carries needed information for the two modes.

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 must carry the return contract — and it does, fully specifying both response shapes, the null/empty/omitted-map distinctions, and the precedence rule. 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% and the single parameter's origin (list_api_tests) is already in the schema, so the baseline is 3. The description earns an extra point by tying the parameter's presence/absence to distinct return shapes, which is meaning the schema does not convey.

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

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

States a specific verb (read) and resource (where API test alerts are delivered), and immediately scopes it per-test. It clearly distinguishes itself from siblings like get_notification_destinations (source-level default), list_alert_channels (name resolution), and set_api_test_destinations (mutation). An agent can route correctly without opening any schema.

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

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

Explicitly documents the two invocation modes — with apiTestId vs without — and what each returns. It names the alternatives for adjacent needs (get_notification_destinations for the source default, list_alert_channels to resolve UUIDs, set_api_test_destinations to change routing), which is exactly the when/when-not guidance required.

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

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

Annotations already make the read-only, idempotent, non-destructive profile clear, and the description adds substantial semantics on top: RATE_LIMITED means HTTP 429, no retry occurred, Retry-After is honored (retryAfterSeconds), and the run is excluded from uptime. It also explains traceId as the W3C traceparent value for cross-referencing target-side logs, and protocolRevision/previousRevision semantics for MCP tests.

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

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

The purpose and the traceId payoff are front-loaded, and nearly every clause carries information an investigator needs. The middle is dense with parenthetical clauses, making some sentences long, but 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?

There is no output schema, so the description carries the return-value burden and does so: it enumerates outcomes, timing, assertion failures, traceId, retryAfterSeconds, and the MCP revision fields. It also discloses the one hard limitation (captures available on the HTTP API only), leaving nothing critical unstated for a paginated 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?

With 100% schema coverage, the schema already documents from/to/page/size/status/apiTestId, so the baseline is 3. The description adds value by framing the filters as an optional time window and status, and by defining what each outcome status actually means; it also flags the important scope limit that request/response captures are not exposed here.

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

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

States a specific verb and resource ('Page through an API test's recent run history') plus the identity of the parent entity (apiTestId). It is clearly distinct from siblings like get_api_test (config) and get_uptime (aggregate), and it names its investigative purpose explicitly.

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

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

"Use this to investigate why an API test is unhealthy" gives a concrete trigger, and the description notes optional filtering by time window and status. It stops short of naming alternatives (e.g., use get_uptime for aggregate availability, get_api_test for configuration), so the routing is implied rather than stated.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes beyond them by explaining the read-before-write intent and the consequence of skipping it ('silently drops panels and drifts the SQL'). It does not cover failure behavior for an unknown id, which keeps it at 4.

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

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

Two sentences, front-loaded with the action and followed by the workflow rationale. Every clause carries information; nothing is redundant with the schema or annotations.

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

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

For a single-parameter read tool with rich annotations and no output schema, the description covers purpose, usage sequencing, and the concrete cost of misuse. An agent has everything needed to call it correctly in the dashboard-editing workflow.

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?

One parameter with 100% schema description coverage; the schema already explains that id is 'as returned by mint_dashboard'. The description adds no syntax, format, or scoping detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return the stored definition for an existing dashboard') rather than restating the name. The framing as the read-side of an edit workflow cleanly separates it from list_dashboards/describe_dashboards and positions it against update_dashboard.

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 prescribes the sequence ('Call this before update_dashboard') and names the alternative practice to avoid ('rather than rebuilding a definition from memory'). The condition that selects this tool is unambiguous.

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

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

Annotations already establish read-only, idempotent, non-destructive, so the bar is lower, yet the description still discloses substantial behavior: a ten-item newest-first sample cap, the 21-day default window, that includeSeries output 'is large', and the semantics of unexplainedFailedCalls. That is real operational context beyond the structured fields.

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

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

Front-loads the core purpose and then the diagnostic workflow, so the important material comes first. It is dense and packed into long comma-heavy sentences, but nearly every clause carries information an agent needs; only the sheer length keeps it from a 5.

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

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

With no output schema, the description carries the full burden of describing the return shape, and it does: calls/failures vs baseline, environments with counts, sampled failedCalls fields, per-issue outcomes, and unexplainedFailedCalls. Defaults and the includeSeries switch are covered, so nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning: it explains the interaction between from and to defaults, that environment restricts counting to a single deployment environment, and that includeSeries should be left out when only numbers/samples/issues are needed. It goes beyond restating the schema without fully specifying value formats.

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 a specific verb and resource ('Fetch one flow by id') and immediately situates it against siblings by naming the two sources of an id (list_flows, an issue's impact). An agent can tell exactly what this returns without opening the schema.

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

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

Gives explicit routing: to read what went wrong on a route, take the fingerprint from the newest failedCalls entry and call get_issue with include=occurrences, or take the traceId to the trace tools; and states that a missing fingerprint means the trace is the only lead. It also states when to omit includeSeries. This is when-to-use, alternatives, and a conditional fallback.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description earns credit by disclosing the exact JSON shape returned and explaining that sessionEntries is the raw Claude Agent SDK transcript of tool calls/results/messages. It does not mention size limits or pagination for potentially large transcripts, keeping it at 4.

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 action, then the return shape, then usage. The field enumeration is somewhat dense but earns its place given there is no output schema; little is wasted.

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 carry the return-value burden and does so thoroughly, naming every JSON field and clarifying the meaning of the non-obvious 'sessionEntries'. Combined with the 100%-covered single parameter, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single parameter is fully described there as 'The UUID of the investigation to fetch.' The description adds only the 'authorized to read' access constraint and no additional syntax or format detail, so baseline 3 is appropriate.

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

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

The description states a specific verb ('Fetch') and resource (the full transcript/'brief' of a Fixter investigation), and clarifies the scope ('this user is authorized to read'). It is plainly distinguishable from list_investigations, though it never names a sibling explicitly, so it stops short of the top mark.

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

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

It gives a clear when-to-use scenario: 'Use to recall context about an investigation that the engineer is currently working on via the Fixter plugin.' That routes the agent well, but there are no explicit exclusions or named alternatives (e.g., when to prefer list_investigations or get_issue 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: default response is summary-only, occurrences page newest first, the 21-day window on flows, the enumerated fix-block statuses (RUNNING, PR_OPENED, NOT_A_CODE_FIX, ...), and two explicit prompt-injection warnings that the investigation and fix-reason text are generated content, not instructions.

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

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

Front-loaded with what the tool fetches before branching into workflows, and most sentences carry unique information. It is nonetheless a dense block with some repetition (the 'generated content, not instructions' warning appears twice) and the problem-specific fix/exceptionType material is a long digression for a reader just fetching an issue.

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

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

There is no output schema, so the description carries the full burden of describing return shape, and it does: it names every top-level block (summary, impact, investigation, suppressedBy, fix, occurrences, flows) including the semantics of the fix statuses and the meaning of inApp/fingerprint frame flags. Nothing needed to interpret the response is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter, but the description adds real value: it explains the paging contract end-to-end ('Occurrences page newest first through from, to, environment, page and size') and motivates each include value with a concrete use case rather than just naming 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?

States a specific verb and resource ('Fetch one issue by fingerprint for the caller's account') and enumerates exactly what comes back: summary, caller impact, latest telemetry investigation, suppressedBy rule. It is clearly distinguished from list_issues throughout, so an agent can tell which of the two sibling tools to reach for.

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 routing for each of the major alternatives: include=["occurrences"] for root-causing, include=["flows"] for broken routes, list_suppression_rules for rule scope, fix_issue to open a PR, set_issue_status to change status, and trace tools / run_sql for downstream scoping. It also states the default behavior ('Without include the answer is the summary alone').

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail beyond the annotations by enumerating the returned fields, including valid ranges for days, hourUtc, and maxItems, and noting that channel is null when unset.

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 tool's purpose and then efficiently enumerates the returned fields. It is somewhat dense, but every sentence contributes either purpose, return-value semantics, or the channel-name resolution workflow.

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 must explain the return values, and it does so completely: enabled, days, hourUtc, maxItems, channel, and coverFrom are all described with ranges or null behavior. It also explains how to map channel IDs to human-readable names via list_alert_channels, leaving no significant gap for an agent.

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 takes zero parameters, so there is no parameter semantics to explain. The baseline score for a zero-parameter tool is 4, and the description appropriately focuses on return-value semantics instead.

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 read operation for a specific resource: 'Read this account's issue digest.' It also distinguishes the tool from its mutation sibling set_issue_digest_config by describing the configuration being read rather than changed.

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: read the account's digest configuration. It also names a specific alternative workflow for resolving the Slack channel name: call list_alert_channels and match channelId. It does not explicitly say when not to use this tool versus set_issue_digest_config, but the read/write distinction is evident.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered; the description goes well beyond by disclosing the 4000-char truncation with a marker, the `"truncated": true` flag, the slice protocol, and how to chain `offset=nextOffset` to read on. This is exactly the extra behavioral context the annotations cannot express.

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

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

Front-loaded correctly — purpose, then usage, then the slicing sub-protocol, then the plain return. It is dense and somewhat sprawling across return-value and slicing details, but nearly every sentence carries operational information the agent needs given there is no output schema.

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

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

With no output schema, the description carries the return-value burden and does so: it describes both the no-path return (the log object) and the slice return (logId, path, chars, offset, text, nextOffset, matches, keys). Combined with the truncation and continuation semantics, an agent has everything needed to call it and consume the result.

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

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

Although schema coverage is 100%, the description adds meaning the schema does not: `path` accepts message, an attribute name, or a JSON path like `body.items[2].name`; `find` starts the slice just before its first match at/after offset; `length` defaults to 20000 and caps at 50000. It also explains the interaction between offset, nextOffset, and matches.

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 first sentence states a specific verb and resource ('Fetch a single log by its logId') and immediately scopes the return ('all attributes flattened in... and the message'). It goes on to name the siblings it is not — `logs` for scanning and `run_sql` for custom column selection — so an agent can route without opening any schema.

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

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

Explicit when-to-use ('Use after a lean `logs` scan when you need the body of one row') and explicit alternatives ('For custom column selection use run_sql'), plus a distinct slicing sub-mode with its own invocation recipe. Both the retrieval case and the long-value case route the agent correctly.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description wisely spends its words elsewhere: it discloses default scoping to sourceInstanceId so replicas aren't interleaved, the strict-before/strict-after semantics, chronological sort order, and the queryStats payload. This is meaningful behavior beyond the annotations.

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

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

Front-loaded one-line purpose, then defaults and return shape under clear labels. Every section carries information, though the Defaults block partially duplicates schema content and the formatting is somewhat sprawling for a 4-parameter 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?

With no output schema, the description takes on the burden of describing the return shape (anchor, before, after, queryStats) and it does so completely, including sort order. An agent has everything needed to call and interpret this 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%, so the baseline is 3; the description restates the same before/after/sameSource defaults the schema already gives, which is redundant. It earns the extra point by explaining why sameSource defaults to true (same pod/process, avoiding interleaved replicas) — conceptual meaning the schema does not convey.

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

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

States a specific verb+resource+scope: return logs chronologically around a given logId, with the anchor included. The framing as 'neighbour' queries clearly distinguishes it from get_log and logs, which fetch a single log or a stream rather than a window around an anchor.

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?

Names the concrete question it answers ('what happened right before/after this alert?') and explains the sameSource=false alternative for cross-pod queries with an example. It stops short of explicitly contrasting with named siblings like get_log or logs, so it isn't a full when/when-not routing statement.

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

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

Annotations already cover readOnly/idempotent/non-destructive, but the description adds genuinely non-obvious delivery semantics: null channelIds means fallback to the customer's email channel plus default channel, an empty list means notifications are off. It does not state auth or rate-limit behavior, but the fallback/disabled distinction is the crucial behavioral fact for this 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?

Front-loaded: the core answer and return semantics come first, the sibling-routing caveat second. Every sentence carries information, though the final paragraph is dense enough that the description runs long for a one-parameter getter.

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

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

With no output schema, the description takes on return-value disclosure and does it well by decoding the null vs empty-list cases, plus it scopes the read to the source row and points to the two tools needed for rule/test-level destinations. Nothing required to call or interpret it is missing.

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

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

Schema coverage is 100% and the single 'source' parameter is fully documented in the schema (including validation behavior against routable sources), so the description adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Show which notification channels a source's notifications are delivered to') and immediately scopes it as the source-wide row, explicitly distinguishing it from the per-rule and per-test destination getters. An agent can tell it apart from get_alert_rule_destinations and get_api_test_destinations without opening any schema.

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

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

Explicitly names when this tool is insufficient ('a source read alone does not tell you where a routed rule's or test's notifications go') and routes the agent to the two exact alternatives by name. Both the when-to-use and the when-not-to-use conditions are stated with no inference required.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description does add real behavior: span ordering by (timestamp, spanId), truncation with spansTruncated/truncationHint, verbose attribute flattening, and long-value capping. It stops short of stating the practical cost of spanSize limits or pagination specifics beyond the truncation hint, so it is valuable rather than exhaustive.

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

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

Front-loaded with the core purpose and the correlate comparison before any detail, and paragraphs are task-scoped (whole trace vs slice). It is long and slightly repetitive in re-explaining the slice parameters that the schema already lists.

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 enumerates the returned fields, the truncation contract, and the full slice return shape. An agent can call it, interpret truncation, and continue reading without guessing.

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?

Coverage is 100%, and the description still adds meaning the schema cannot: how find and offset interact (the slice starts just before the first match at or after offset), how to continue via offset=nextOffset, and what the slice return shape contains. That is interaction semantics, not restatement.

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 (returns the spans of a single trace plus a summary) and a distinct second mode (with spanId and path, read one long value of one span). It explicitly contrasts itself with the correlate sibling, so an agent can distinguish the two without opening either schema.

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

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

Gives an explicit routing rule: prefer correlate when investigating a trace because it returns the same spans plus logs and exemplars; use get_trace only when the span tree alone is needed. It also routes raw-column needs to run_sql, and explains the exact when-to-use condition for the slice mode.

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

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

Annotations already cover read-only, idempotent and non-destructive semantics, but the description adds genuinely valuable behavior: the exact uptime formula, the exclusion of ERROR, MISSED and RATE_LIMITED runs, and the default 24-hour window. It does not describe response shape in detail, but for a read-only statistical tool this is strong added context.

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

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

Three short sentences with no waste: the core action, the formula/exclusions, and the default window are presented in a logical, front-loaded order.

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

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

For a read-only metric tool with no output schema, the description covers what is returned (uptime percentage, latency percentiles, run counts), how uptime is computed, which run statuses are excluded, and the default time window. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents apiTestId, from and to including their defaults. The description reinforces the default-window behavior but adds no syntax or format detail beyond what the schema already provides; 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 states a specific verb and resource: computing an API test's uptime percentage, latency percentiles and run counts. It is clearly distinct from raw-run siblings like get_api_test_runs in substance, but never names an alternative or explicitly contrasts itself with any sibling tool.

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

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

Usage is only implied: an agent can infer this is the aggregation/statistics tool rather than a raw-run fetcher, but there is no explicit when-to-use, when-not-to-use, or named alternative such as get_api_test_runs.

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

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

Annotations already establish the safe read-only profile, and the description adds meaningful behavioral context beyond them: responses are JSON, results are scoped to the authenticated customer, `sources: null` means all sources including future ones, and the two ID fields have different routing purposes.

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

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

It is front-loaded with the core action and return format, then moves into the high-value ID-routing distinctions. Every sentence contributes concrete information, and there is no filler.

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

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

With no output schema and an empty input schema, the description carries the full burden and does so well: it explains what is returned, the key fields, which identifier feeds which downstream tool, and the meaning of null `sources`.

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?

This tool has zero input parameters, so there is no parameter semantics to add and the schema baseline of 4 applies. The description instead adds useful return-field semantics for `id`, `channelId`, and `sources`.

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 gives a specific verb and resource: list the authenticated customer's registered Slack/email notification channels. It also distinguishes the returned `id` from `channelId`, which is the main source of confusion for sibling tools that consume these 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?

It provides clear downstream usage context by naming `save_alert_rule`/`set_alert_rule_delivery` and `set_issue_digest_config` and specifying which identifier each expects. It does not explicitly state when not to use this tool or name a direct alternative, so it stops short of the top score.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive behavior, so safety is covered. The description adds meaningful context beyond that: 'Secret material is never included' discloses a security-relevant return constraint, and the field list signals what the caller receives. It stops short of describing pagination or empty-result behavior.

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

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

Two short sentences with zero waste. The return-shape constraint is front-loaded and the follow-up action is stated second, so the most important information is not buried.

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

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

For a zero-parameter, read-only list tool with no output schema, the description supplies the return fields (id, name, type) and the secret-exclusion guarantee, which is what an agent needs to call and consume it. Pagination/limits are not mentioned, a minor omission.

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 takes zero parameters, so there is nothing to document and the baseline is 4. The description does not need to compensate for any parameter gap.

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

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

The description states a specific verb and resource ('List your stored credentials') and narrows scope to three fields (id, name, type). The second sentence ties it to API tests, but it never explicitly distinguishes itself from the similarly named sibling list_investigation_agent_context_credentials, leaving a small ambiguity an agent must resolve from the tool name.

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?

'Use the returned id to attach a credential to an API test' implies the workflow this tool feeds into, but gives no explicit when-to-use guidance or when-not-to-use/alternative comparison against the other credential-listing and credential-mutating siblings. Usage is inferred rather than stated.

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

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

Annotations already declare a safe read, and the description goes well beyond them: it explains that results are a page not the full list, that the count fields always cover all tests regardless of filters or paging, that 'currentRevision' is null until the first MCP run, and that RATE_LIMITED means the target throttled the prober rather than being down. That is exactly the interpretive context an agent needs.

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

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

It is dense but front-loaded: purpose first, then state semantics, then pagination mechanics, then filtering advice. A few clauses restate schema defaults (size, page) and could be trimmed, but almost every sentence carries information the agent would otherwise have to guess.

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

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

There is no output schema, and the description fully covers the return shape ('apiTests', 'totalElements', 'page', the four aggregate counters) and how to iterate pages to completion. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: the default 50 / max 200 sizing, the zero-based paging loop termination condition, and that 'search' is a case-insensitive name-contains plus combinable with 'state'. It slightly restates the schema's defaults but adds the interaction 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+resource ('List your API tests') plus the scope (paged, with configuration and health state), which is clearly distinct from the sibling get_api_test. It never names a sibling explicitly, so the differentiation is inferred from the paged-list framing rather than stated.

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 concrete guidance: 'Use this to see what is being watched' and 'Narrow with search and/or state instead of paging through everything when you are looking for specific tests or only for failing ones.' It covers when to filter vs. page, but offers no explicit alternative such as get_api_test for a single test's detail.

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

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

Annotations already establish the safe read-only/idempotent profile, and the description adds genuinely new behavior: newest-first ordering, that results carry ids and links, and the meaning of the truncated flag with a remediation path. It does not address result-size limits or pagination beyond the flag.

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, zero filler, and the purpose is front-loaded before the filter guidance and the truncation caveat.

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, no-output-schema list tool, the description covers what is returned (ids, links), how it is ordered, and how to handle truncation, so an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the schema already defines titleContains as a case-insensitive substring match. The description adds intent-level framing (finding 'the one dashboard the user is describing'), but no syntax or format information 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?

States a specific verb and resource ('List dashboards stored for this account') and even specifies ordering and returned fields ('newest first, with ids and links'). It does not explicitly differentiate itself from the single-item sibling get_dashboard, so it stops short of a 5.

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

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

'Pass titleContains to find the one dashboard the user is describing instead of scanning the full list' gives clear when-to-use guidance for the filter, and the truncated note tells the agent how to reach more results. It never names an alternative tool or an explicit when-not condition, so it is not 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 readOnlyHint/idempotentHint already covering safety, the description adds real substance: the 21-day window, what each row aggregates (24h calls, 7d caller hits), the definition of a caller hit (failed while carrying exception or 5xx), and row ordering (worst first). Return-shape detail is strong for a tool with no output schema; it stops short of one or two edges but is well above the annotation bar.

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

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

Front-loaded with the core definition, then row contents, then routing advice. Some middle sentences are dense and run long, but every sentence carries information (window, aggregation, ordering, alternative). Only mild tightening would be possible.

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

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

For a read-only list tool with no output schema, the description is complete: it defines the entity, the window, the per-row metrics, the ordering, and the follow-up call. An agent can decide to call it, know what comes back at a conceptual level, and know where to go next.

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

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

Schema coverage is 100% and each parameter has its own description, so the schema already supplies semantics. The description adds the default window framing (last 21 days, last 24 hours) but doesn't explain includeLeaves or environment interactions beyond what the schema says. 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?

States a specific verb (List) and resource (flows), then defines 'flow' concretely as 'a service and a route or job name' and scopes the time window (last 21 days). An agent can distinguish this from get_flow and from generic list_* siblings without opening any schema.

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

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

Gives an explicit use case ('which routes are hurting callers... read callersHit7d') and routes to the alternative ('to see every issue behind one route, call get_flow with that row's id'). When-to-use and when-to-use-something-else are both stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds genuinely new context: the auth requirement ('available to any authenticated user') and the null-semantics of 'operation' and 'expiry', which the agent could not infer from the empty schema.

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

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

Two sentences, zero filler, with the identity and access constraint front-loaded before the entry-shape detail. Every clause carries information.

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

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

With no output schema, the description correctly compensates by enumerating what each returned entry contains, including null semantics for operation and expiry. It omits ordering, pagination, or result-size behavior, which is the only remaining gap for a list 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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The field-level explanation it does give pertains to return values rather than inputs, which is appropriate here.

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

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

States a specific verb (list) and resource (ignore rules) scoped to 'the calling tenant', which cleanly separates it from create_ignore_rule and delete_ignore_rule in the sibling set. An agent can identify the operation without opening the schema.

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

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

The description never states when to use this tool versus alternatives, nor any exclusions or prerequisites. The 'READ' note is a permission statement, not usage guidance, and no sibling (e.g. create_ignore_rule) is referenced as a routing alternative.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds meaningful traits beyond them: values are never returned by this tool or any other, credentials are write-only, and the grouped return shape. That write-only disclosure is the single most decision-relevant fact about this tool and would not be inferable from annotations.

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

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

Two tight sentences, no filler, with the scope statement front-loaded and the return-shape detail immediately after. The write-only caveat earns its place because it prevents an agent from attempting to retrieve secret values.

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 parameters, no output schema, and annotations already declaring the safety profile, the description carries the remaining burden well: it explains the grouping, the fields returned, the timestamp, and the write-only constraint. Nothing an agent needs in order to call this correctly is absent.

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 takes zero parameters, so there is nothing for the description to disambiguate; per the baseline for parameterless tools this sits at 4. No parameter guidance is needed or missing.

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

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

States a specific verb (List) and resource (the authenticated customer's stored monitoring credentials), plus exactly what the output contains: provider name, configured key names, and latest updated-at timestamp. It implicitly separates itself from the sibling list_api_test_credentials by narrowing scope to 'investigation agent context' credentials, though it never names that sibling explicitly.

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

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

The description establishes context (the authenticated customer's stored monitoring credentials) so an agent can infer this is the read path for inspecting configured providers, but it never states when to call this versus list_api_test_credentials or the set_investigation_*_credentials siblings, and gives no prerequisites or exclusions.

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

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

With readOnlyHint, idempotentHint and destructiveHint already declared, the description goes further by describing the return shape (id, publicSlug, headline, flow, createdAt, claimedBy with null semantics) and the filter scope. It does not disclose truncation/pagination behavior — what happens when more than `limit` results exist is unstated.

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, all load-bearing: scope first, then return shape, then the id/publicSlug routing, then filters. No filler and the most important constraint (newest first, two flows only) is front-loaded.

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

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

With no output schema, the description carries the return-value burden well by enumerating the summary fields and null semantics. The only meaningful omission for a list tool is what happens past the limit (truncation vs. cursor), which leaves the agent guessing about completeness of results.

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

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

Schema description coverage is 100%, so 'from'/'to' and 'limit' are already documented, including default 20 and max 100. The description's note that from/to bound createdAt largely repeats the schema wording, adding no new syntax or semantics; baseline 3 applies.

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

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

States a specific verb (List), the exact resource (the authenticated customer's Fixter investigations), narrows scope to two flows, and specifies ordering (newest first). An agent can tell what it retrieves without opening the schema.

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

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

It gives clear downstream context — the returned id feeds get_investigation_brief and start_investigation, and publicSlug feeds start_investigation only — which effectively tells the agent when to reach for this tool. It stops short of naming a competing alternative (e.g. list_issues) or an explicit when-not-to-use condition.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint, and the description adds substantial behavioral context beyond them: the default list omits ignored and suppression-rule-matched issues, how suppressedByRuleOnly answers from the rules alone, that impact is not computed for problems, that PRIORITY sort is refused for non-PROBLEM kinds, and that suppressedOnly wins over other suppression args when combined. These are real operational traits an agent would otherwise miss.

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

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

It is front-loaded with purpose and when-to-use followed by filter/next-step guidance, and most sentences carry distinct decision value. It is, however, a dense prose block for a 14-parameter tool; some suppression-argument explanation is verbose and would read better as bullets, so not a perfect 5.

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 14 optional parameters, no output schema, and high complexity, the description supplies everything needed to call it correctly: valid kinds, sort/direction interplay, suppression precedence, priority/recommendation filtering, and what each result carries (hasInvestigation, hasFix, impact, priority/recommendation). No material gap remains for an agent to invoke it.

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

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

Schema coverage is 100%, but the description still adds meaning beyond it: it explains that query matches frames as well as title/type/service, that sort=FIRST_SEEN+direction=asc starts at the oldest issue still present, that CALLERS orders by 7-day caller impact, and documents filter-value consequences (e.g. priority=URGENT,HIGH, recommendation=FIX) plus argument precedence. This goes well past the schema's enum lists.

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 sentence states a specific verb and resource ('List the issues and problems Fixter has already detected in the caller's telemetry') and then clearly distinguishes an issue from a problem (kind=PROBLEM). It names what each issue groups and carries, so an agent can tell list_issues apart from get_issue, search logs, or list_investigations without opening any schema.

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

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

It explicitly says when to call this first (investigating an error, broken feature/job, service that won't start, deploy health) and prescribes the next step (get_issue on a fingerprint, then search logs). It also names concrete filter combinations for specific questions (status=NEW for new, sort=FIRST_SEEN/direction=asc plus open status for the longest-broken), which is explicit when-and-how guidance with 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely non-obvious behavior: the per-(service, metric) deduplication semantics and the fact that each entry's lastSeen is service-scoped, enabling dead-emitter detection. It stops short of stating result limits, ordering, or pagination, which keeps it from a 5.

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

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

Front-loaded with the critical grain and routing information, and the dead-emitter use case earns its space by explaining why lastSeen matters. The trailing Params section is partly redundant given 100% schema coverage, and the Returns line restates the opening sentence, so it is efficient but not waste-free.

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

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

There is no output schema, and the description compensates by describing the return shape ('array of metric summaries, one per (service, metric) pair') and enumerating the fields each entry carries (type, unit, description, temporality, monotonicity, lastSeen). Only result ordering and any cap on the number of returned pairs are left unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by clarifying what the from/to window actually filters on — 'entries seen within the range', i.e. last-seen time rather than metric values — which the schema's generic 'Start of window' text does not convey. The `service` explanation largely repeats the schema.

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

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

States a specific verb and resource ('List available metrics') and immediately defines the grain of the result: one entry per (service, metric) pair, with a concrete example of a metric emitted by three services yielding three entries. This is distinguishable at a glance from the sibling `metrics` tool, which is named explicitly.

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

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

Explicitly routes the agent: 'Use this to discover what metrics exist, and which services emit them, before calling metrics.' The alternative (`metrics`) and the condition that selects it (discovery first, query after) are both stated, so the agent does not have to infer the relationship between the two 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?

Annotations already declare the read-only, idempotent, non-destructive profile, so the bar is lower; the description still adds real value by explaining the coverage semantics (matches, seen in last day, notifications withheld) and how negated=true renders as != in the rule expression. It does not address auth, rate limits, or pagination, keeping it below 5.

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

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

Purpose is front-loaded, followed by return-value semantics and then the call-ordering workflow. Mostly every sentence earns its place, though the expression/negation aside is dense for an agent that may not need to render the rule verbatim.

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 correctly carries the burden of describing the return shape and coverage fields, and it supplies the follow-up workflow. The remaining gap is that it never contrasts with the sibling list_suppressions, which an agent selecting among 60+ tools would need.

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 takes zero parameters, so the baseline is 4; there is nothing for the description to clarify here.

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

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

States a specific verb and resource ("List the suppression rules of the caller's account") and details what each returned rule contains. However, it never distinguishes itself from the near-identical sibling list_suppressions, leaving the agent unable to tell the two apart without inspecting schemas.

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

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

Explicit when-to-use ("Call this first when asked why an issue is missing from a list or why a card never arrived") and clear routing to the follow-up tool (manage_suppression_rule with action=delete/update/preview/create). No when-not guidance and no mention of the alternative list_suppressions, so it falls short of a full 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description goes further by disclosing the auth requirement and, crucially, the semantics of returned fields: null signal means all signals, null operation means whole service, maxSeverity caps severity, null expiresAt means never expires. That is meaningful behavioral context beyond the annotations, though nothing is said about pagination or result size limits.

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 paragraphs, front-loaded with the purpose followed by a compact field-semantics key. Every sentence carries information, though the second paragraph is dense enough that it could be bulleted for faster scanning.

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

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

With no output schema, the description does well to explain the shape and meaning of returned entries, and the auth note is helpful. However, it never resolves the overlap with list_suppression_rules, list_ignore_rules, and suppress_signal/unsuppress_signal, which is the main thing an agent needs to route correctly in this crowded family.

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 takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The schema is an empty object and the description correctly does not invent parameter details.

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 with scope ('List the calling tenant's active alert suppressions'), so an agent knows exactly what is returned. It does not, however, distinguish itself from the very similar siblings list_suppression_rules, list_ignore_rules, or suppress_signal/unsuppress_signal, leaving the 'suppression vs suppression rule' boundary unstated.

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 only guidance is 'READ: available to any authenticated user', which is a permission note rather than a when-to-use statement. There is no indication of when to prefer this over list_suppression_rules, nor any mention of the mutation siblings that create or remove suppressions.

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 annotations already covering read-only/idempotent safety, the description adds substantial context beyond them: sort order (timestamp, logId descending), default window and limit with the 1000 ceiling, string truncation via maxStringChars and the 'more' marker, pagination via nextCursor including truncationHint behavior, and guidance to send users to explorerUrl rather than reproducing output.

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

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

Front-loaded with purpose and routing, then organized into Defaults / Patterns / Returns sections that an agent can scan. It is long, and the verbose-attributes sentence partially duplicates the schema, but almost every line carries routing or return-shape 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?

No output schema exists, yet the description fully documents the return object (logs, nextCursor, truncationHint, explorerUrl, queryStats) and pagination semantics. Nothing material is left for the agent to infer before calling or continuing a page.

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 earns extra by restating the effective defaults (from = 1h before, to = now, limit = 100) and by pairing parameters into usage patterns. Minor gap: it references 'verbose=true' and 'maxStringChars' but adds little about how maxStringChars interacts with the cut marker beyond what the schema says.

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 ('Find logs matching filter criteria within a time range') and immediately positions itself as the default entry point for log queries. It distinguishes itself from siblings by naming list_issues, run_sql, and get_log with the conditions that select each.

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 routing: call list_issues first when investigating an error, use run_sql for raw columns/substring/regex, use get_log for one row with every attribute. It also states the negative case ('Substring or regex search: not supported here') and gives concrete named patterns for error, trace, and token searches.

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

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

Annotations declare destructiveHint=true and readOnlyHint=false, but the description carries far more: matched issues keep recording and keep status while being hidden from lists and notifications; update/delete rearm hidden issues immediately with nothing resent and withheld cards not resent; the response reports rearmedIssues; preview stores nothing; duplicate rules are refused. These are exactly the mutation side-effects an agent needs and are not inferable from the annotations.

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

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

The purpose and action set are front-loaded, and the dense workflows are appropriate for a genuinely complex six-parameter tool. It is nevertheless long and repeats the 'call list_suppression_rules' instruction three times, so a little telescoping would tighten it without losing 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?

With no output schema, the description compensates by describing what preview returns (match count, last-day count, one page of issues most-recent-first) and what update/delete return (rearmedIssues). Combined with the condition grammar and the refusal/validation rules, an agent has everything needed to call and interpret this 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 already 100%, so the schema explains each parameter's role. The description still adds real semantics the schema lacks: match='all' vs 'any' join behavior, the one-condition rule being stored as 'all', star wildcards matching whole values case-insensitively, ENVIRONMENT matching the whole issue, and negation semantics including issues lacking the field. It overlaps the schema on a few points (wildcards, 1-5 conditions) but adds beyond 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 first sentence names a specific verb set (add, retarget, remove, dry-run) on a specific resource (one suppression rule of the caller's account) and ties it to the 'action' parameter. It further distinguishes itself from siblings by explaining the single-issue alternative (set_issue_status with IGNORED) and the read-side tools (list_suppression_rules). An agent can separate this from create_ignore_rule or suppress_signal without opening a schema.

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

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

Explicit step-by-step workflows are given for each of the three real use cases: silencing a set of issues (preview then create then verify), retargeting (list, preview, update), and removing (list, delete). It also names the when-not case ('To silence a single issue instead ... call set_issue_status') and the precondition ('read the existing rules before adding one'). This is about as complete as usage guidance gets.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantial runtime behavior: server-side step coarsening with authoritative 'step' field, zero-filled buckets, truncation via maxChars with truncatedRows, and exactly when explorerUrl is null (groupBy, filters, or omitted service). This is far beyond what structured fields convey.

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

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

Long but well-partitioned into purpose, per-type output shape, param notes, returns, bucket semantics, and coarsening. Front-loaded with the core purpose, though a few passages (e.g. the per-type output block) are verbose enough to slow scanning.

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

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

Despite having no output schema, the description documents return shape per metric type, the full returns field list, coarsening reasons, and truncation behavior. For an 8-parameter, nested-object query tool this is complete enough that an agent could call and interpret it correctly.

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

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

Schema coverage is 100% so the baseline is 3, but the description meaningfully extends it: groupBy/filters accept data-point (not resource) attributes, a metric field wins over an identically named attribute, key regex constraints, filter values are safe as-is, and step's unit set/minimum are restated with examples. This adds real semantics 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?

Opens with a specific verb+resource ("Query a metric time series") and immediately differentiates itself from siblings by referencing list_metrics for name discovery and run_sql for the quantile limitation. An agent can distinguish this from list_metrics and run_sql without opening a schema.

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

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

Gives clear context: pull metricName/service from list_metrics, omit service to aggregate across all services, and use explorerUrl when the user asks to see/plot/visualize rather than charting manually. It does not fully spell out when to prefer this over run_sql or other sibling tools, so it stops short of a 5.

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

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

Goes well beyond the annotations: title collisions are refused, broken definitions are rejected, every panel's SQL is executed against live data, errors block the link while warnings ship with it. It also explains link stability (update_dashboard changes the same link) and why duplicates are harmful. Annotations only declare the generic write/safety profile.

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

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

Dense but nearly every sentence carries actionable content (workflow, refusal semantics, validation behavior, composition). Mild criticism: the actual purpose sentence is buried in the second paragraph behind workflow guidance, so the opening is not maximally 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 complex write tool with no output schema, it covers the mutation's side effects, validation behavior, and even the two artifacts to hand back (link and id). It stops short of describing the exact response/error payload shape, which is the main remaining gap.

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

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

Schema description coverage is 100%, so both optional overrides (range, refresh) and definitionJson are already documented in the schema, which points to describe_dashboards for the JSON shape. The description adds little parameter-level detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific chain of actions ("Validate, ground, store, and mint a Fixter dashboard link") and names the object precisely. It distinguishes itself from update_dashboard (edits an existing link), describe_dashboards (defines the JSON), and list_dashboards/get_dashboard (discovery), so an agent can route without opening a schema.

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

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

Explicit when-to-use and when-not: check list_dashboards then get_dashboard, and prefer update_dashboard over minting a duplicate. Prerequisites are spelled out (call describe_dashboards first, compose with run_sql), and it states the tool verifies rather than designs.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds meaning beyond them: 'never persists anything, never throws for an invalid spec,' and the critical problems[] vs warnings[] distinction (warnings never block saving). The FIELD_NEVER_OBSERVED + NO_MATCHING_DATA diagnostic and the anomaly-backtest approximation caveat are exactly the kind of behavior an agent cannot get from annotations.

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

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

Key routing ('call this before save_alert_rule') and the most dangerous trap (dataCoverage before totalWouldFire) are correctly front-loaded, and the dense length is partly justified by 21 parameters. It loses a point for redundancy: the derivedGroupBy example and the 'label is what rule pages and alert titles show' point are duplicated verbatim from the schema description, and the 'Both fields are required and non-blank' note restates the schema's required array.

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 carries full burden for return values — and it enumerates every field (normalizedSpec, problems[], backtest with dataCoverage and per-series values, seasonality with suggestedMode, warnings[]) plus how to interpret them. For a 21-parameter, nested-object tool with no annotations on failure behavior, nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so 3 would be the baseline, but the description adds cross-parameter semantics the schema cannot express: fromQuerySql overrides the structured fields, groupBy and derivedGroupBy compose, anomaly conditions replace comparator/warningThreshold and require an empty groupBy, and a parenthesis/space in a groupBy string is rejected. These are interaction rules, not restated field meanings.

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 first sentence gives a specific verb+resource with scope: it 'validates and normalizes a candidate rule spec and, when valid, backtests how often it WOULD have fired.' The 'preview→save gateway' framing and the explicit 'Call this before save_alert_rule' line make it unmistakable against the sibling that actually persists rules.

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

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

It states exactly when to call it (before save_alert_rule, to calibrate), when-not to act (fix problems[] before saving; don't loosen the threshold on NO_MATCHING_DATA), and the exclusive modes (structured fields vs fromQuerySql). It even explains downstream behavior — save_alert_rule re-runs identical validation — removing guesswork.

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

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

Annotations only flag destructiveHint and idempotentHint; the description adds the concrete blast radius (every auto-investigation rule bound to the channel is CASCADE-deleted), states the change is unrecoverable, notes the ADMIN auth requirement, and discloses the return shape. That is substantial context beyond the structured fields.

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

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

Three sentences, each carrying unique weight: what is removed, who may do it, and the irreversible consequence. The actionable warning is front-loaded and nothing is restated from the schema or annotations.

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

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

For a single-parameter destructive tool with no output schema, the description covers the resource, the authorization requirement, the irreversible cascade behavior, and the return value. An agent has everything needed to call it correctly and to warn a user first.

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

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

With 100% schema description coverage on a single parameter, the schema already documents channelId including its format example. The description only refers to it generically and adds no format, sourcing, or constraint information beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (Remove) and resource (a Slack channel id from the notification-channel list), with scope limited to the authenticated customer. It is clearly distinguishable from the sibling add_alert_channel and from the alert-rule 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?

Gives the key precondition (ADMIN only) and a strong caveat about cascade side effects, which tells an agent when this is safe to call. It does not name a preferred alternative or a when-not-to-use condition relative to siblings like delete_alert_rule, so it stops short of full routing guidance.

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

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

Annotations only cover read-only/idempotent safety; the description adds the behaviors that actually change call outcomes: a 7-day default window unless a lower timestamp bound is given, zero-fill only for a specific query shape, 4000-char cut cells with a follow-up get_trace/get_log path, moreRows/nextOffset only when a top-level ORDER BY exists, and priorWindow erroring without literal ISO bounds. It also lists hard limitations (no INSERT/UPDATE/DELETE/UNION, no CROSS JOIN, no SYMMETRIC BETWEEN, JOINs need qualified refs), which the annotations do not imply.

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

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

Front-loaded with purpose and preferred-tool routing, then organized into labeled sections (Clauses, Sources, Functions, Limitations, Time bounds, Examples, Returns) with worked examples, so it is navigable rather than a wall. It is still very long and repeats some dialect caveats (case-sensitivity of regexp_matches vs contains vs matches), which costs a point against strict concision.

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

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

With no output schema, the description carries the return contract itself and does so thoroughly: columns/rows/queryStats, explorerUrl availability and when to send the user there, priorWindow shape, cut-cell markers, and pagination hints. Combined with the schema, sources and limitations, an agent has everything needed to compose a correct statement on the first try.

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 earns above that by tying parameters together operationally — offset is described as reading on from a previous nextOffset with the same sql, maxChars shrinks the `shown`/`head` budget on cut cells, and compareWithPriorWindow requires literal ISO bounds or priorWindow returns an error.

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 a specific verb and resource: "Execute a read-only QuerySQL SELECT against the observability data", and immediately scopes it to the QuerySQL dialect over logs/spans/metrics. It explicitly disambiguates from siblings (correlate, get_trace, aggregate_spans, list_issues) rather than leaving the agent to guess.

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 routing rules: "Prefer purpose-built tools when they fit: use correlate when you have a trace id... aggregate_spans to find where errors or latency are concentrated... Use run_sql for ad-hoc analysis that the other tools don't cover", plus "Call describe_schema first" and "Call list_issues with that text as its query first" for error-text searches. When-to-use and when-to-use-something-else are both stated.

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

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

Goes far beyond the annotations (destructiveHint=true, readOnlyHint=false). It discloses the whole-object replace semantics (omitted fields are cleared, including description set to null), the status/delivery carve-outs that survive omission, the ADMIN-only create-only channelIds behavior and its rejection when combined with ruleId, and the problems[]-vs-warnings[] contract including the FIELD_NEVER_OBSERVED code. This is exactly the non-obvious mutation behavior an agent needs.

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

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

Front-loaded with the create/update decision and the replace warning before the field-level detail, and organized under clear headers. It is long, and several blocks (unit, description, expression) are near-verbatim repetitions of the schema, but the size is defensible for a 27-parameter tool.

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

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

For a 27-parameter, nested-object, no-output-schema mutation tool, the description covers the safe-call workflow, the create/update/anomaly/static mode selection, the validation and error/success contracts (problems[] vs warnings[] vs rule), and the routing to sibling tools. Nothing an agent needs to call 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 baseline is 3, but the description adds genuine cross-field and precedence semantics the schema does not: expression takes precedence over fn, groupBy rejects expression-like strings (pass them in derivedGroupBy), derivedGroupBy requires both expression and label, and channelIds is create-only/ADMIN-only. It largely mirrors the schema for several fields rather than extending them, so it falls short of a clean 5.

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

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

Opens with a specific verb+resource+scope: 'Create or update an alert rule for the calling tenant in one call.' It explicitly distinguishes itself from siblings by naming set_alert_rule_status, set_alert_rule_destinations, get_alert_rules and preview_alert_rule, and it states what it cannot do (compound multi-condition rules). An agent can identify and route to this tool without opening the schema.

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

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

Gives explicit when-to-use branching (omit ruleId to create, supply ruleId to replace), tells the agent to preview_alert_rule first and re-send full specs after fetching with get_alert_rules, and names the alternative tools for status/destination changes. It also states an exclusion: compound rules must be built in the web editor.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds material context beyond them: ADMIN-only auth, that destinations are not stored on the rule but forwarded to the notification gateway, and that unknown channel ids are rejected with no change. It does not explicitly reaffirm the idempotent/replace semantics, but the 'replace'/'forwarded' wording is consistent with the annotations.

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

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

Purpose and the bold 'WRITE: ADMIN only' flag are front-loaded, then parameters, then behavioral notes. Despite its length every sentence carries distinct information (inheritance, off-switch, precedence, validation).

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, yet the description covers everything an agent needs for a mutation call: auth level, destination source, inheritance/clear semantics, invalid-id behavior, and where to read the current value. Nothing material is missing.

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