Rius

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

Annotations cover the safety profile (readOnly=false, idempotent=true, destructive=false), and the description adds substantial context beyond them: the alert stays open and keeps counting occurrences, nothing can force-close it, and the tool requires an interactive OAuth connection because an API key is not a user. That auth constraint is exactly the kind of behavior an agent must know before invoking.

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

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

Front-loads the core action, then the ack-vs-resolve distinction, then the auth constraint, then parameter notes and a runnable example. Every sentence earns its place and nothing is 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?

An output schema exists, so return values need no explanation. For a low-complexity write tool with two parameters, the description covers purpose, the ack/resolve boundary, the auth requirement, and both parameters — 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 0%, so the description carries the full burden and does: alert_id is 'the alert's id, from list_alerts' (source documented) and workspace accepts an id, name, or org-name/workspace-name form with a stated default. Both parameters are fully disambiguated beyond the bare schema types.

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

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

States a specific verb and resource ('Acknowledge an alert: record that a human has seen it') and immediately distinguishes the action from the sibling concept of resolving ('Acknowledging is NOT resolving'). An agent can tell this apart from get_alert/list_alerts 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 clear context for use (a human has seen the alert so it stops notifying) and an explicit when-not by ruling out resolution ('only the detector resolves it, once the condition clears'), plus an auth precondition. It does not name a concrete alternative tool, which keeps it just short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), yet the description adds real behavioural context: grouping reads span events so the window is capped like an unindexed query, refusals surface in the reply, and pagination is interpretable because the response reports total errored spans for the window. It does not disclose rate limits or exact cap values, which keeps it at 4 rather than 5.

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

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

Front-loaded with the core purpose, then the semantic caveat, then parameter docs, then worked examples. Every section earns its place, though the console-attribution sentence and the dual restatement of the count/failed_traces distinction are slightly 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?

An output schema exists, yet the description still explains the row shape (count, distinct traces, last occurrence, instances, sample trace ids) and clarifies what the count does and does not mean. Combined with full parameter coverage and window-cap disclosure, 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 0%, so the description carries full burden and does so for all seven parameters: workspace formats and default, hours default and interaction with start/end, absolute RFC3339 bounds with override behaviour, agent as this span's identity with guidance to read it from list_agents, instance narrowing, and limit default plus server max. It adds meaning well beyond the bare 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, resource and grouping key ('Group a window's errored spans by failure class — exception type and a normalised message') and explicitly distinguishes itself from agent_traces_summary by contrasting `count` with `failed_traces`. An agent can tell this apart from the sibling summary tools 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 examples make concrete usage contexts explicit (per-agent failure triage, cross-agent weekly rollup, instance-level narrowing), and the text routes to get_agent_trace for sample ids and list_agents/list_agent_traces for name discovery. It clearly marks the boundary with agent_traces_summary, but never states an explicit when-not-to-use rule, 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 readOnlyHint/openWorldHint annotations: ordering (newest first), event-time vs page-load-time semantics, the meaning of each kind, the timing rule for 'lost' (sweep tick that noticed) plus the last_seen_at caveat, and the provenance note that this is the same read the console timeline uses. It does not cover pagination behavior or row shape, but the annotations already establish the 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?

Front-loads purpose, then event semantics, then a per-parameter block, then worked examples — a sensible order. It is long, and the multi-line parenthetical for `lost` is dense, but nearly every sentence adds operational detail rather than 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?

An output schema exists so return values need not be detailed, yet the description still explains the key event payload fields (last_seen_at, open_trace_count, open_traces). For an 8-param read tool with zero schema descriptions, this is complete enough to call correctly.

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

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

Schema coverage is 0%, so the description carries the full burden and does so for all 8 parameters: workspace id/name/org-qualified form with default, hours default and its interaction with start/end, RFC3339 format with example values and override precedence, agent exactness, agent+instance composition, limit default and server max (200), and the opaque cursor's origin.

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 ('lifecycle log of a workspace's agent instances') and enumerates the exact event kinds it returns (started/finished/lost/recovered). It also explicitly distinguishes itself from the sibling list_agents by noting 'stale' is a read-time status there, never an event here.

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?

Routes the agent to alternatives with conditions: use list_workspaces to discover workspaces, list_agents for current status rather than history. Two concrete example queries ('when did planner's copies die today', 'everything that happened to inst-planner-01 this week') demonstrate when to reach for 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 readOnlyHint=true, yet the description adds substantial semantics beyond them: failed vs errored traces are defined and must not be summed, error rate is defined as errored/traces, a trace counts whole in its first-span bucket, sparse buckets mean absent is not zero, and buckets over 1000 are refused. It also discloses that this is the identical read the Rius console performs, so figures reconcile.

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 KPI list and the core routing rule, then per-parameter documentation, then examples — a logical order with almost no filler. It is long, and seven examples plus two separate expository paragraphs on failed/errored semantics push it toward the verbose end, but for a ten-parameter tool with zero schema coverage that length is largely earned.

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?

An output schema exists so return values need not be described, yet the description goes further by naming which KPIs are returned and how derived figures are computed. Combined with complete parameter documentation and failure-mode notes (rejected filter clauses, refused grain), an agent has everything needed to call it correctly 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 description coverage is 0%, so the description carries the full burden and does: it documents all ten parameters including defaults (hours=24), override precedence (start/end over hours), the workspace org-name/workspace-name disambiguation form, the agent-vs-service fallback distinction, filters grammar and composition, bucket grain auto-selection thresholds, and the day-bucket UTC-midnight partial-first-bucket caveat.

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 (summary KPIs for agent traces) and enumerates exactly what is returned: trace count, LLM calls, error rate, sessions, cost, token usage, latency/TTFT percentiles. It also implicitly distinguishes itself from the sibling list_agent_traces by framing this as the aggregate read of the same population, and explicitly names the console Drift figure it backs.

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 conditions: use list_workspaces to discover workspace ids, call describe_search_catalog before guessing a filter key, and read an agent name off list_agent_traces rather than guessing. It also states when to reach for group_by="bucket" (trend questions) versus the flat window figures, plus seven worked scenario examples.

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/no-open-world, but the description adds substantive behavior: rows are ROOT-scoped like registry fields, ordered newest-seen first per dimension, capped at 50 per dimension with totals counting past the cap, and row contents (traces, failed traces, failed rate, first/last seen). These are the operational traits an agent needs and none are in 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 the core purpose and the two-dimension warning, followed by equivalence, then parameters, then two focused examples — a strong structure. It is verbose in places (the repeated workspace parenthetical), but nearly every sentence adds load-bearing 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?

With an output schema present, return values need not be enumerated, yet the description still previews row fields. Combined with full parameter documentation, usage routing, cap/ordering semantics, and named siblings, an agent has everything required 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 0%, so the description must carry all parameter meaning — and it does. Every one of the six parameters is documented with its default and semantics, including RFC3339 format for start/end with the 'overrides the hours-derived value' precedence rule, workspace name-vs-id-vs-org/workspace disambiguation, and instance as a narrowing filter.

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 ('The versions ONE agent ran in a time window') and then carefully disambiguates the two dimensions (agent definition vs. service build) that an agent could easily conflate. It names the sibling it feeds into (compare_agent_versions), so it is unmistakable against its neighbors.

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

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

Explicitly states when to use it: 'Use it to learn which two values to hand compare_agent_versions, or to see when a version appeared.' It also gives the equivalent agent_traces_summary query with exact filter syntax, so an agent knows the overlap and when to pick one over the other.

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 declare readOnlyHint/openWorldHint, so the description carries real behavioral weight and does: delta units (percentage points for failed rate, percent of base otherwise), the dash-means-unknown convention, the sub-20-trace noise caveat, and the refusal-rather-than-misanswer policy. This is exactly the kind of edge-case disclosure annotations cannot provide.

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

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

Front-loaded with the core purpose and the change semantics before the parameter block, and every paragraph earns its place. It is dense rather than bloated, though the prose runs long enough that a tighter version could lose nothing.

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 nine-parameter comparison tool with an output schema, everything an agent needs to call it correctly is present: sourcing of exact version strings, refusal boundaries, delta interpretation, and ambiguity resolution for workspace names. Nothing material is left to inference.

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

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

Schema description coverage is 0%, so the description must compensate fully and does: every one of the nine parameters is explained, including where to source values (list_agents, agent_versions, list_workspaces), the base/head orientation rule, the dimension enum with a 'build' synonym, and the start/end-vs-hours override precedence.

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 and scope: 'Two versions of ONE agent side by side over the same window', then enumerates exactly which six metrics are compared. It names the sibling relationship ('agent_traces_summary twice') so an agent can tell it apart from the single-version summary tool 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?

Explicitly routes the agent: this is agent_traces_summary applied to two versions, and it specifies the refusal condition (deployments whose filter registry lacks the version field). The two worked examples ('did v8 make it worse' vs 'compare the last two builds') show the dimension choice in context, and the dimension note warns the two identity axes are not interchangeable.

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

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

Beyond the annotations, the description discloses important behavioral details: this provisions a real outbound effect, alert content leaves the platform via HTTP POST, and the payload can contain model output from span error messages. It also states the required `channels:manage` capability, giving the agent a clear safety and permission picture.

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

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

The description is front-loaded with purpose and outbound-effect details, then moves to capability requirements, parameter semantics, and a concrete example. Every sentence earns its place because the schema provides no parameter descriptions, and the structure is easy to scan.

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

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

Given a multi-type creation tool with 0% schema description coverage, the description covers purpose, side effects, required capability, all parameter semantics, defaults, and an example. Since an output schema exists, return values need not be explained, so nothing essential is missing for correct invocation.

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

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

With 0% schema description coverage, the description fully compensates by documenting all seven parameters, including constraints (name 1-120 characters, recipients 1-20 addresses), type-specific semantics (`url` for webhook, `slack_channel_id` for Slack), the Slack-connection prerequisite, and workspace format details. This adds substantial meaning beyond the bare schema.

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

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

The description uses a specific verb and resource: create a delivery channel for alerts, naming the three supported types (webhook, email, Slack). It distinguishes itself from sibling create_alert_rule by explaining that this tool provisions the destination rather than the rule, so an agent can pick correctly 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 clearly gives context for when to use the tool: creating a place for alerts to be delivered, with each channel type explained. It does not explicitly name alternatives or exclusions, such as using update_alert_channel for edits, 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 cover the safety profile (readOnlyHint=false, destructiveHint=false), and the description adds substantial context beyond them: rules are ANDed with no OR, filters are ANDed, values bind verbatim (the lowercase `llm` gotcha), channel_ids requires the `channels:manage` capability, omitting channel_ids falls back to the region default webhook, and enabled defaults to true.

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 purpose followed by per-parameter semantics and two worked examples; the structure is easy to scan. It is long, but nearly every line maps to an undocumented parameter or a non-obvious behavioral constraint, so little is wasted — the two examples are the only arguably expendable material.

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 7-parameter mutation tool with 0% schema coverage is fully documented, and since an output schema exists the description is not obliged to explain return values. 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 description coverage is 0%, so the description carries the full burden and does: name length bounds, rules element shape with the lt/lte/gt/gte/eq operator set plus the 1–10 count and (metric, aggregation) uniqueness constraint, window_minutes range, filter shape with eq/ne/in/not_in arity rules, channel_ids source, and workspace id/name/`org/workspace` 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+resource ("Create a custom alert rule") and immediately distinguishes this from predefined rules and from update_alert_rule. An agent can tell it apart from siblings like create_alert_channel or update_alert_rule 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?

Explicit prerequisites ("Call describe_alert_catalog first"), an explicit exclusion ("Predefined rules cannot be created"), and a named alternative ("Use update_alert_rule to configure one"). It also routes to list_alert_channels for channel_ids, so both the when and the where-next are covered.

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 write, non-idempotent profile, and the description adds material context beyond them: admin access is required, the plaintext key is shown exactly once and never retrievable again, headless-mode minting is blocked to prevent key amplification, and why certain scopes are withheld. These are exactly the operational facts an agent needs before calling.

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 requirement, the one-shot key warning, the availability restriction, parameter docs, and examples. Every sentence carries information, though the two example blocks add length that a shorter inline illustration might have covered. Minor efficiency cost, no real waste.

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

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

An output schema exists, so return values need not be explained, and the description instead covers the non-obvious return semantics (key shown once). Combined with prerequisites, mode restrictions, and full parameter docs for a 3-param, 0%-coverage schema, 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 description coverage is 0%, so the description carries the full burden and does: workspace documents accepted id/name/'org-name/workspace-name' forms and the default, name states it is a display label, and scopes enumerates the valid values and defaults ('ingest', optionally 'read') plus the exclusions. This fully compensates for the empty schema.

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

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

Opens with a specific verb+resource: 'Create a new API key in one of your workspaces.' It also distinguishes itself from the alert-channel/rule creation siblings by stating that alert-management scopes are deliberately not mintable here. An agent can identify the resource, scope, and boundary 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?

Explicit when-to-use and when-not: unavailable when the MCP connection is authenticated by an API key (headless mode), and the agent is told to mint from an interactive OAuth session or the console instead. It also routes the agent to list_workspaces for workspace discovery. 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?

Goes well beyond the destructiveHint=true annotation by disclosing the silent side effect on dependent rules ('loses that destination silently ... does not start failing loudly'), the required `channels:manage` capability, and the two-phase confirmation requirement. These are exactly the behavioral facts an agent cannot infer 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?

Front-loaded with the destructive verb and irreversibility, then consequence, then alternative, then auth, then params. Well ordered, but the trailing example block restates argument shape that the schema and the preceding param sentences already cover, adding some length without new information.

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

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

For a destructive, capability-gated tool with an output schema, the description covers consequences, prerequisites, the confirm handshake, and parameter sourcing. Nothing needed to invoke it safely is missing, and return values are rightly left to the output schema.

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

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

Schema description coverage is 0%, so the description carries the full load and does: channel_id is sourced from list_alert_channels, confirm is the phrase from the first call's output, and workspace accepts id/name or org-name/workspace-name with a default. All three parameters are disambiguated beyond their bare types.

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

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

States a specific verb and resource ('Delete a notification channel') and immediately qualifies it with 'Irreversible.' It also names related siblings (delete_alert_rule, list_alert_channels, update_alert_channel), so an agent can place it precisely in the tool graph.

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 gives a when-not-to-use path: 'Consider update_alert_channel with enabled false instead, which is reversible.' It also documents the two-call preview+confirm flow, which is non-obvious invocation guidance rather than mere context.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it specifies that the entire firing history is destroyed, that the action is irreversible, and that a confirm phrase from the first call gates the second. That is exactly the extra context an agent needs before a destructive call.

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

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

The destructive and irreversible nature is front-loaded in the first sentence, followed by the call protocol, the preferred alternative, and then per-parameter notes plus a concrete example. Every sentence earns its place and nothing is 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 destructive, multi-step tool this covers the full operational picture: irreversibility, the confirm handshake, the preferred non-destructive alternative, eligibility limits, parameter sourcing, and defaults. Since an output schema exists, the description rightly does not spend space explaining return values.

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

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

Schema coverage is 0%, so the description must carry the burden, and it does: ref is the custom rule's uuid from list_alert_rules, confirm is the phrase returned by the first call's output, and workspace accepts an id, name, or org-name/workspace-name with a default noted. Each parameter gains meaning not present in the bare 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 ('Delete a custom alert rule AND its entire firing history') and immediately distinguishes scope with 'custom' and 'Irreversible'. It also names the sibling alternative (update_alert_rule) and rules out a class of targets (predefined rules), so an agent can tell it apart without opening another 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/when-not: prefer update_alert_rule with enabled false to keep history and stay reversible, and predefined rules cannot be deleted at all. It also documents the required two-call confirm protocol, so the invocation sequence 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 declare readOnlyHint=true and openWorldHint=false, so safety is covered. Beyond that the description adds real behavioral context: it discloses that the response includes 'constraints the catalog itself does not advertise' and that the field parameter returns values 'actually seen in this workspace over the last 24h', which is non-obvious. It stops short of auth, rate-limit, or pagination notes, so not a 5.

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

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

Front-loaded with the core purpose and the create_alert_rule prerequisite, then parameter docs, then examples. Every element is useful, though the two fenced examples add bulk for a two-parameter read tool and the description is on the long side. Nothing is wasted, but it could be tightened.

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?

An output schema exists, so return values needn't be spelled out, yet the description summarizes what comes back and how it differs by parameter. An agent has the prerequisite ordering, both parameter semantics, and the response shape — nothing needed 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 description coverage is 0%, so the description carries the full burden and does so: it documents both parameters with their default behavior, the three accepted workspace id forms, and a concrete field example ('service') plus the 24h lookback semantics. This meaning is entirely absent from the schema, so the description is doing genuine 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+resource: describes what you can alert on, listing the exact contents returned (filter fields, metrics with supported aggregations, operators, allowed window). It also distinguishes itself from create_alert_rule and, implicitly, describe_search_catalog, so an agent can separate it from siblings 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?

Explicitly says 'Read this before calling create_alert_rule', giving a clear when-to-use trigger and a sequencing prerequisite relative to a named sibling. The two worked examples map common user intents to the two call shapes, reinforcing when each parameter applies.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description goes well beyond that with a genuine cost model: promoted columns are cheap over any window, attr./resource. keys cost ~10x and are only accepted over windows of 31 days or less. That operational context is exactly the behavioral detail an agent needs and 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?

Front-loaded with the core instruction, then the grammar/cost model, then per-parameter notes and examples. It is longer than strictly necessary and the grammar explanation is a touch expansive, but nearly every line earns its place.

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

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

An output schema exists, so return values need no explanation. For a zero-required-parameter, read-only discovery tool, the description covers purpose, sequencing, cost, and every parameter including worked examples.

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

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

Schema coverage is 0%, so the description carries the full burden and does so for all four parameters: workspace (accepts id, name, or org/workspace, with default), field (both spellings), prefix (with an example), and hours (default 24). Worked JSON examples reinforce each parameter's intent.

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: describing the filter grammar for traces and spans. It is clearly distinguished from the sibling list_agent_traces and list_spans, which it positions itself as a prerequisite to.

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 to read this before composing `filters` for list_agent_traces or list_spans, and warns that a guessed key is a rejected call. The cost model gives ordered guidance ('narrow with a column first, then add one'), leaving little to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description adds real behavior: include_content is off by default because content can be very large, captured content is subject to workspace privacy controls (capture_content=False or masks yield nothing), and the attribution field is blank only when the key can't be resolved or the trace predates attribution. That is substantive disclosure beyond the safety 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 tool's action, then parameter docs, then worked examples. Most sentences earn their place, but the multi-sentence digression on the ingest key's own email and its fallback to the creator's email is deeper detail than an agent needs to select or call the 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?

An output schema exists so return values need not be explained, and the description still covers the waterfall layout, the header/row agent attribution, session semantics, and the multi-session per-span column. For a read-only three-parameter tool this is complete.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: trace_id is sourced from list_agent_traces, workspace accepts an id/name/`org-name/workspace-name` disambiguator and defaults to the default workspace, and include_content's semantics and default are spelled out. All three parameters gain meaning not present in the bare 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 plus the exact output shape: 'Get one agent trace's span waterfall (spans in time order, indented by depth).' It also implicitly distinguishes itself from list_agent_traces (enumerating traces) and list_spans (per-span queries) by describing the waterfall-of-one-trace 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 concrete follow-up routing ('pass either name back to list_agent_traces or list_spans as `agent`', 'pass it to `list_spans(session_id=...)` for the rest of that conversation') and states exactly when to set include_content=true. It never states when not to use this tool, but the context for use 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 declare readOnlyHint=true and openWorldHint=false, and the description adds what the agent actually gets back: labels, sample trace ids, and the investigation's written finding when root-cause analysis ran. That conditional return behavior is genuine context beyond the annotations, though permissions or failure modes are not addressed.

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 usage, parameter notes, and a worked example — a sensible order with little wasted text. The JSON example largely restates what the parameter notes already convey, which is mildly redundant but still aids invocation.

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?

An output schema exists, so return structure need not be documented, yet the description still summarizes the key payload fields. Combined with the parameter notes and the list_alerts handoff, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: alert_id is defined as the id from list_alerts, and workspace is explained as an optional id, name, or `org-name/workspace-name` disambiguator with a stated default. Both parameters are fully specified.

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 (one fired alert), and explicitly delimits scope to a single alert including its root-cause finding when present. This clearly separates it from list_alerts and the trace-oriented 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?

"Use this after list_alerts to understand a single alert" gives a clear trigger and names the preceding tool in the workflow. It does not state when not to use it (e.g. versus get_agent_trace for raw trace inspection), so it stops short of full alternative routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real behavioral context beyond that: output varies by auth mode (interactive OAuth vs API key), workspaces are grouped by org when multiple orgs exist, and an unjoined user yields 'none'. This is meaningful disclosure for a read tool, though it omits rate limits or pagination 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?

Front-loads the core purpose, then layers the auth-mode and edge-case nuances in a logical order. It is on the long side for a zero-parameter tool and the example call with empty arguments is somewhat redundant, but nearly every sentence carries distinct behavioral 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 an output schema present the description need not explain return values, yet it still sketches the response shape and the conditions that alter it, and annotations cover the safety profile. Nothing needed to invoke or interpret this zero-parameter read tool is missing.

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

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

The tool takes zero parameters, so the stated baseline of 4 applies; there are no parameters whose semantics could be clarified further. The description's empty-arguments example correctly reinforces that no input is required.

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 ('Get your own identity and access context') and enumerates exactly what is returned (user, orgs with roles, accessible workspaces). The self-scoping implicitly separates it from list_users and list_workspaces, but no sibling is named explicitly, so it falls short of full differentiation.

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

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

Usage is implied — this is the tool to discover your own identity and permission scope — and it usefully explains auth-dependent behavior (OAuth spans all orgs; API key reports only its bound workspace). However, it never says when to prefer this over list_users / list_workspaces or what prerequisites exist, leaving 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses real behavioral traits: status is computed server-side and must not be re-derived from last_seen_at, the meaning of open_trace_count and blank first_seen_at, and the important edge case that trace-only agents never appear with an explanation for missing agents. This is rich context the annotations do not carry.

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

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

Purpose is front-loaded, then field semantics, then parameter guidance, then examples. It is on the longer side, but nearly every sentence adds distinct value; only the example block could be considered marginally redundant for a sophisticated agent.

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 an output schema exists, the description need not explain return values, yet it goes further and documents key fields and their edge cases. Combined with complete parameter guidance and documented missing-agent behavior, 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 description coverage is 0%, so the description carries the full burden, and it does: workspace is explained as an id, name, or org-name/workspace-name disambiguator with default behavior, and agent is explained as an exact-name narrowing filter with the caveat that the server has no native filter and that non-matching replies name agents that do have instances.

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 with scope: 'List a workspace's agent instances with their live status.' It further differentiates from siblings by noting that trace-only agents do not appear, distinguishing it from trace-oriented tools like list_agent_traces and agent_traces_summary.

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

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

It gives clear context ('the same read the Rius console's Agents page makes') and two worked examples of the questions it answers, plus a pointer to list_workspaces for discovering workspace names. It never explicitly names an alternative tool to use instead, so it stops short of full when/when-not/alternatives 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/open-world; the description adds substantial behavior beyond that: cursor-based paging and why not to raise limit, ~10x cost for attr/resource keys with a 31-day window cap, substring-on-attribute refusal, blank-cell semantics for session/user_id/root_status/sent_by, and the any-span-vs-root-span matching asymmetry that would otherwise look like a bug.

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 paging, then per-parameter paragraphs that each earn their place. It runs long and the example block repeats the status/root_status distinction already stated in prose, so a little redundancy, but no filler sentences.

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 16-parameter, zero-schema-coverage, output-schema-bearing query tool, this covers gaps the structured data leaves open: cost tiers, window limits, pagination, filter composition, and the exact failure modes (rejected clause names itself, session search unavailable on older cores, fall back to filters).

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

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

Schema coverage is 0%, so the description carries the full burden and does: every one of the 16 parameters is documented with defaults, override precedence (start/end override hours), enum values, exact-match rules, and composition semantics. The subtle 'root_agent == service means fallback, not two facts' note is exactly the kind of meaning a schema can't express.

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+shape: 'List recent agent traces (one row per trace) newest-first, as a Markdown table.' It also distinguishes itself from siblings by naming get_agent_trace, list_spans, and describe_search_catalog as the follow-on/alternative tools.

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

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

Explicit routing throughout: trace_id feeds get_agent_trace, session feeds list_spans, status+root_status composability is spelled out with concrete slices (recovered vs genuine failures), user_id vs anonymous are declared mutually exclusive, and filters are ordered by cost with a directive to call describe_search_catalog before guessing keys.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses an unusual auth requirement ('needs the channels:manage capability rather than plain read') and reveals that results expose sensitive destinations. That is meaningful context annotations cannot convey, though pagination/result-size behavior is unaddressed.

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 purpose sentence, then usage, capability note, and parameter doc in a logical order. The quoted 'Where do my alerts go?' plus JSON example is mildly redundant but does show the valid empty-arguments call.

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?

An output schema exists, so return values need no explanation, and the description still characterizes the payload. Auth requirement, param semantics, and routing to the create/update tools cover everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description must carry the single parameter — and it does: accepted forms (id, name, org-name/workspace-name), the disambiguation condition, and the default. Nothing about 'workspace' is left ambiguous.

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 where this workspace's alerts can be delivered') and immediately disambiguates from the rule-listing siblings by describing the returned destination content (webhook URL, email recipient list, Slack channel). An agent can distinguish this from list_alert_rules and list_alerts 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?

Explicitly names the downstream use case: find a channel id for create_alert_rule or update_alert_rule. It does not state exclusions or contrast directly with list_alert_rules/create_alert_channel, so it stops short of full when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: predefined rules can be toggled but not created/deleted, the semantics of the `ref` identifier, and the caveat that an empty list may reflect alert-manager not yet reaching the workspace.

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, then layered detail; each paragraph adds distinct information. The trailing JSON example with empty arguments is somewhat redundant for a zero-required-param tool, costing a point but not much.

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?

Complete for this tool. Return values are covered by the output schema, and the description still supplies the interpretive context an agent needs (rule categories, ref semantics, empty-list meaning) to act on results 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 0% and the schema only marks `workspace` as a string with default "", so the description carries full burden. It explains the param accepts an id, name, or `org-name/workspace-name` disambiguator, and that it defaults — fully compensating for the schema 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?

States a specific verb and resource ('List every alert rule in the workspace') and immediately distinguishes the two categories it returns (predefined vs custom). Clear enough that an agent can tell it apart from siblings like list_alert_channels and list_alerts.

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 strong context: it explains the `ref` column is the input to update_alert_rule/delete_alert_rule, and that an empty list may just mean detection hasn't started. It never explicitly states when to prefer this over list_alerts or list_alert_channels, so it stops short of full when/when-not guidance.

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

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

Annotations already cover readOnlyHint and openWorldHint, yet the description adds substantive domain behavior: alerts stay open until the detector resolves them, an open alert with a recent last_seen is still occurring, and the server is unbounded if no window is given (a real performance hazard). This is genuinely useful context beyond the 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?

Front-loads the one-line purpose and the 'what is broken' framing before parameter docs and examples. It is long, but the length is earned given 10 undocumented parameters; only mild tightening 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?

An output schema exists, so return values need not be described. For a read-only, fully filterable list tool the description covers purpose, filtering semantics, edge cases (unbounded scan), and examples — 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 0%, so the description carries the full burden and does so: it defines workspace format, status values, the kind enum and its 'custom' caveat, the distinction between kind and rule_id, and defaults/ranges for hours and limit (at most 200). All 10 parameters are given meaning beyond their names.

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

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

States a specific verb and resource ('List alerts that have fired, newest first') and frames the tool's role as the "what is broken" tool, clearly distinguishing it from get_alert (single) and list_alert_rules (rule definitions). An agent can identify the right sibling 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?

Provides concrete usage context via two worked examples (open alerts now; errors for a service this week) and routes the agent to list_alert_rules as the source of rule_id. It does not explicitly state when not to use it versus get_alert/ack_alert, but the conditions that select it are clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds useful context beyond them: the catalog is identical for every caller and workspace only fills the request path, plus it explains the 'companions' semantics of the response. No rate-limit, auth, or size caveats, but the added behavioral detail is meaningful.

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, followed by usage, parameter docs, and a worked example; each block earns its place. The lead sentence is dense and the companions parenthetical lengthens it, but there is no genuinely wasted text.

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

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

For a three-param, zero-required discovery tool with an output schema and read-only annotations, the description covers purpose, all parameters with valid values, behavioral nuance, and a concrete invocation example. Nothing essential to calling it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does so completely: workspace (name/id, content-invariant), group (filter with concrete examples like cost/latency/ttft), and kind (filter with its three valid values scalar/series/breakdown). This compensates fully for the undocumented 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 ('List every metric the platform knows how to compute') and enumerates the returned facts (unit, nullability, serving read, companions), making the tool's scope unambiguous. It does not explicitly contrast itself with nearby siblings such as workspace_metrics_overview or the other catalog tools, so it falls just short of 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?

States a clear use case: 'Use it to discover exact field names instead of guessing them,' which tells the agent this is a discovery/introspection tool. It never names an alternative or a when-not-to-use condition (e.g., use workspace_metrics_overview for actual values), so there are no explicit 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?

Annotations only declare readOnly/openWorld, but the description adds substantial context beyond them: Markdown-table output shape, the ~10x cost and 31-day cap on attr./resource. filters, the advice to call describe_search_catalog first, and the cross-trace column semantics for session/agent/user_id. This is rich disclosure of behavior annotations cannot carry.

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

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

Front-loaded with purpose, then parameters, then worked examples — a clean structure. It is long and occasionally parenthetical (e.g. comparisons back to list_agent_traces), but for an 18-param tool with no schema docs the length is largely earned.

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 18 parameters, no required fields, an output schema (so return values need not be explained), and only readOnly annotations, the description supplies everything an agent needs to call it correctly, including examples. No material gap remains.

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

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

Schema description coverage is 0%, so the description carries the full burden — and it documents all 18 parameters with defaults, edge cases (start/end override hours), the derived-vs-raw kind distinction, session_id fallback to trace id, and the user_id-vs-anonymous exclusivity. It more than compensates for the empty schema.

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

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

States a specific verb (list) plus resource (spans) plus scope (across every trace in the workspace, not grouped by trace) and explicitly contrasts itself with get_agent_trace's single-trace waterfall. An agent can distinguish it from every sibling 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 explicit when-to-use framing ('find spans by kind/session/agent regardless of which trace they landed in') with two concrete scenarios, and names the alternative tool (get_agent_trace) it complements. 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 only declare readOnlyHint/openWorldHint, but the description adds the operational envelope: TOP-N ranking by server-side cap, q as an equality probe rather than substring search, a hard 31-day window that is refused if exceeded, refusal of out-of-set sort values, and the caveats on anonymous traffic, trace-based coverage, and null cost. This is disclosure well 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 and well-sectioned, with parameters and examples following the framing. It is longer than strictly necessary, though: the 'words are worth keeping straight' exposition and some of the caveat prose lean narrative where a tighter phrasing would lose nothing.

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?

An output schema exists, so return values needn't be spelled out, and the description instead fills every remaining gap an agent needs: entity scope, window semantics and cap, ranking behavior, the id-probe escape hatch, and three figures called out as easy to misread. Nothing material 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 coverage is 0% (bare types and defaults only), so the description carries the full burden and does: all seven parameters are documented with semantics, defaults, and edge behavior (hours vs start/end precedence, workspace name disambiguation, sort's allowed set and refusal, limit's server max, q's exact-match-only rule). This is exactly the compensation a low-coverage schema needs.

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 framing ('END USERS as a ranked register') and immediately scopes the entity by contrasting it against two look-alikes: console logins and org members. It also disambiguates the whole vocabulary chain (org/workspace/end user), so an agent can tell exactly what population this returns before 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 downstream routing: read a user_id here and pass it to user_activity_summary or list_agent_traces(user_id=...). It also states the exact condition that selects the `q` path (a user outside the top-N) and how q behaves when it misses, which is the main alternative-use decision for this tool.

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

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

Annotations cover safety (readOnlyHint=true, openWorldHint=false), but the description adds behavioral detail the annotations cannot: OAuth logins see every org grouped by org name, while API-key connections see only the bound workspace. That auth-dependent scope difference is exactly the kind of context an agent needs before interpreting results.

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 purpose, then scope, then usage, then a compact example. The example JSON block with empty arguments is a small luxury for a no-parameter tool, but it is short and illustrative rather than 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?

An output schema exists, so return-value detail is not needed. The description covers the two things an agent could not infer: the auth-dependent result scope and how the returned workspace values are consumed by other tools. Nothing material 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?

Zero parameters, so the baseline is 4. The description does add meaning by explaining the workspace identifier formats (id, name, org-qualified name) that this tool's output feeds into, which is useful context even though there is no input to document.

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 workspaces you have access to (id and name)' — and immediately scopes what is returned. No sibling in the list does workspace enumeration, so an agent can route to it 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?

Explicitly says when to use it: 'Use it to find the right value for the `workspace` argument of the trace, metrics and alert tools.' It even explains the three acceptable forms of that argument, removing any guesswork about downstream usage.

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

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

Annotations already flag destructiveHint=true, idempotentHint=true and openWorldHint=true, but the description goes well beyond them: secrets are preserved unless resubmitted, the type field is immutable, repeated delivery failures cause automatic disabling, and the call requires the `channels:manage` capability. These are exactly the operational facts an agent needs before mutating a channel.

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 behavioral rules, then a per-parameter glossary, then a worked example — a logical progression with almost no filler. It is on the long side, but every section carries information not available in the structured fields, so the length is defensible rather than 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?

A mutation tool with destructiveHint=true, no schema descriptions, and no enum hints — the risky categories — yet the description covers partial-update behavior, immutability, auth capability, auto-disable recovery, and workspace disambiguation. An output schema exists, so return values need not be described. Nothing an agent needs to call this safely 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 0%, so the description carries the full burden — and it does: channel_id (source: list_alert_channels), name (new label), url (https POST target for webhooks), recipients (full replacement list, not a merge), enabled (delivery on/off), and workspace (id, name, or `org-name/workspace-name` disambiguation, with default noted). The 'full replacement' wording for recipients is semantics the schema cannot express.

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 ('Change a notification channel') and immediately enumerates the three shapes of change (rename, re-point, enable/disable), which cleanly separates it from create_alert_channel and delete_alert_channel in the sibling list. An agent can identify the tool's job 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?

Explicitly states partial-update semantics ('Only what you pass changes'), a hard exclusion with a redirect ('A channel's type cannot be changed — create a new one instead'), a recovery scenario (auto-disabled channels, pass enabled true after fixing), and points to list_alert_channels for obtaining channel_id. When-to-use, when-not-to-use, and the alternative are all present.

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 substantial context beyond that: disabling stops detection with permanently unfilled history gaps, mixed rule shapes are refused with a corrective message, and an empty channel_ids list re-points delivery to the default webhook rather than silencing. These are exactly the non-obvious behaviors 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?

It is long but justified by ten parameters and zero schema coverage, and it is well front-loaded: the core action, then `ref` resolution, then the destructive warning, then per-parameter detail. There is minor redundancy where the bullet list restates points already made in prose (e.g. `ref`, `window_minutes`), which 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?

An output schema exists, so return values need not be described, and everything else an agent needs is present: the destructive permanence warning, the two config shapes, delivery re-pointing semantics, permission requirements, and workspace disambiguation. Nothing material is left uncovered for a 10-param mutation 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 description coverage is 0%, so the description carries the entire burden, and it documents all ten parameters with real semantics: `ref` format, the predefined-vs-custom split for `config`/`rules`, the full-replace semantics of `rules` and `filters`, `window_minutes` placement rules, and the channels:manage requirement for `channel_ids`. This is maximal compensation for a documentation-free 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+resource ("Reconfigure or toggle one alert rule") and immediately scopes it to "predefined or custom," distinguishing it from create_alert_rule and delete_alert_rule. It names the sibling it depends on (list_alert_rules) and the catalog tool (describe_alert_catalog), so an agent can tell exactly which tool 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?

Explicitly tells the agent where to obtain `ref` (list_alert_rules) and where to find bounds (describe_alert_catalog), and prescribes which config shape applies to which rule type. It also states the failure mode when shapes are mixed, giving clear when-to-use-which guidance rather than leaving it to inference.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds much more: the result is a rollup, not a trace list; it returns "the same figures the Rius console's user page shows"; matching is against any span of the trace, not just the root; and it warns against conflating Failed vs Errored traces. That is genuine behavioral context the annotations cannot carry.

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

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

Purpose is front-loaded, followed by parameter docs and then four examples that each exercise a distinct path (default window, custom window, anonymous, filters). Every section earns its place for a 7-param tool, though the four worked examples plus the console-equivalence note make it longer than strictly necessary.

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

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

With an output schema present, return values need not be enumerated, yet the KPI list still tells the agent what to expect. Combined with full parameter coverage, the user-scope semantics, the Failed/Errored caveat, and the sibling cross-references, 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 0% across 7 parameters, so the description carries the full burden and does so: user_id sourcing and span-matching semantics, anonymous as a mutually exclusive alternative, workspace formats including the `org-name/workspace-name` disambiguator, hours default with its interaction with start/end, RFC3339 formats for both bounds, and the filters clause grammar with a pointer to describe_search_catalog.

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 ("Summary KPIs for ONE end user's activity over a time window") and enumerates exactly which KPIs are returned. It explicitly distinguishes itself from siblings: the field names "match agent_traces_summary", the id comes from `list_agent_traces`, and the result is "a rollup rather than a trace list you have to fold yourself".

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 a concrete when-to-use trigger ("someone arrives with a complaint and an identifier") plus a worked query phrasing. It also spells out the mutually exclusive choice ("Pass either `user_id` or `anonymous`, not both"), clarifies anonymous is "a real subject, not an error case", and routes to `list_agent_traces` / `describe_search_catalog` for adjacent needs.

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 declare readOnlyHint and openWorldHint, yet the description adds substantial behavioral context beyond them: server-decided bucket grain from window length, the distinction between window-relative and UTC-calendar buckets, clipped first/last buckets, and the critical null-vs-measured-0 semantics plus degraded metrics being absent rather than zero. This is exactly the kind of disclosure that prevents misreading the result.

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 before parameters and examples, and each block earns its place by resolving a real ambiguity (grain, clipping, null semantics). It is on the long side and the parameter prose is dense, but there is no filler or repetition.

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

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

An output schema exists, so return values need not be restated, and the description instead supplies the interpretation rules that the output schema cannot convey (clipped buckets, null vs 0, degraded metrics). For a zero-required-param read-only overview tool, nothing an agent needs to invoke and correctly read 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 0%, so the description must carry the full parameter burden and it does: workspace (id/name/org-name/workspace-name plus default and discovery via list_workspaces), hours (default 24, grain rules), minutes (for 'last 10 minutes', ignored when 0), breakdowns (default true), series (default false, verbose). Every parameter gets meaning and defaults beyond the bare JSON types.

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

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

Names a specific verb and resource ('Aggregated health of a whole workspace over a time window') and then enumerates the concrete metrics returned (volume, cost, tokens, latency percentiles, TTFT, error rates, ranked breakdowns). It explicitly positions itself against siblings by framing the output as what you check 'before drilling into individual traces with list_agent_traces / get_agent_trace.' An agent can distinguish it from agent_traces_summary or user_activity_summary 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 an explicit usage trigger ('Use this to answer "how is my workspace doing"') and names the alternative tools (list_agent_traces / get_agent_trace) that handle the drill-down follow-up. It does not state exclusions relative to the other summary siblings (agent_traces_summary, user_activity_summary), so the when-not guidance is incomplete.

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