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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description adds that the output is a delta against a past window, but says nothing about failure modes, window-matching behavior, or limits beyond the schema, and the second sentence is largely rationale rather than disclosure.

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

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

Two short sentences with the operation front-loaded and no wasted preamble. The second sentence is somewhat editorial but does justify the baseline approach, so it mostly 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 not be described, and annotations carry the safety profile. Still, for a 6-parameter tool at 50% schema coverage, the description leaves since, compare_with, and account_ids unexplained and does not address the required aggregations-only constraint on nrql_select.

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 50% (where, event_type, nrql_select are documented; since, compare_with, account_ids are not). The phrase 'same window in the past' loosely explains the since/compare_with pairing, but the description gives no format, default, or interaction detail for the undocumented parameters.

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

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

The description names a specific operation (compare an aggregate against the same window in the past) and clarifies that the result is a delta versus a baseline. This distinguishes it semantically from generic query siblings like run_nrql, but it never explicitly names an alternative tool or its distinguishing condition.

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 implies when the tool is worthwhile ('a regression visible as a delta ... more conclusive than an absolute value'), which is useful framing. However there is no explicit when-to-use/when-not guidance and no routing to run_nrql or run_nrql_async for the plain-query case.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: the golden metrics are the actual NRQL New Relic uses for that entity type and can be run as-is via run_nrql. That is useful, but it leaves gaps such as error/not-found behavior for an unknown guid.

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

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

Two short sentences, front-loaded with the action and return contents. The second sentence earns its place by explaining what the golden metrics are and how to use them. Minor room to tighten but no filler.

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

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

An output schema exists, so return values need not be restated, and annotations carry the read-only safety profile. For a single-parameter lookup the description covers the essentials, with the only real omission being explicit routing versus search_entities.

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

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

Schema description coverage is 100% and the single guid parameter is already documented as 'Entity GUID returned by search_entities'. The description adds no format, syntax, or sourcing detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get one entity') and enumerates what comes back (tags, golden metrics, relationships). It does not explicitly contrast itself with the sibling search_entities, so an agent must infer the difference from 'one' vs. search.

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

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

Usage is only implied: 'Get one entity' suggests retrieving a single known entity, presumably after search_entities, but the description never states when to use this rather than alternatives or what prerequisites exist. The run_nrql mention is a pointer to a related tool, not guidance on selecting this one.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — results are aggregated by error class rather than returned raw — but says nothing about the default time window (1 hour), the default cap (20), or whether aggregation can hide individual events.

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

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

A single front-loaded sentence with no filler, which is structurally sound. It is arguably over-terse given four parameters and a grouping behavior worth explaining, but nothing in it is wasted.

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

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

The output schema exists, so return values need not be explained. However, with 0 required parameters and three of four parameters undocumented in both schema and description, plus an undefined 'recent', an agent lacks enough to call this confidently beyond the default configuration.

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 only 25% (only service_name is documented), and the description contributes nothing about limit, since, or account_ids. Notably, 'recent' in the description is ambiguous while the schema quietly defaults since to '1 HOUR AGO' — the description could have resolved that and did not.

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

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

The description states a specific verb and resource ('Show recent transaction errors') plus an aggregation mode ('grouped by error class'), which is more than a restatement of the name. It does not, however, differentiate itself from near-neighbors like summarize_log_errors or search_logs, so an agent must infer the distinction.

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

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

There is no statement of when to use this tool versus the alternatives, and no prerequisites (e.g., that a time window is assumed). The word 'recent' is the only usage signal, and it is left undefined.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a genuine behavioral detail (results are chronological spans of a single trace), but says nothing about pagination, the time-window default, or what happens when the trace_id is unknown.

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

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

Two tight sentences with no filler, and the core action ('Get the spans of one distributed trace') is front-loaded ahead of the optional pairing hint.

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

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

The output schema exists, so return values need not be described. But for a tool whose behavior depends heavily on an undocumented default time window (since=3 HOURS AGO) and limit, the description leaves an agent unable to predict what a bare call will return.

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 only 25% – only trace_id is documented in the schema. The description names trace_id in the pairing sentence but adds no meaning for the three other parameters (limit, since, account_ids), leaving the 3-hour default time window and the 1000-span cap entirely unexplained.

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

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

The description states a specific verb and resource ('Get the spans of one distributed trace') plus the ordering guarantee ('in chronological order'), so an agent knows exactly what it returns. It also implicitly distinguishes itself from the log-oriented siblings by naming search_logs as the complementary tool.

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

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

It gives one concrete usage pairing ('Pair this with search_logs on the same trace_id'), which is useful context. However, it offers no guidance on when this is preferable to other exploration tools (get_entity, run_nrql, search_entities) and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the 'for an account' scoping and says nothing about pagination behavior despite the cursor parameter, so it contributes little beyond structured data.

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

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

A single tight sentence with no wasted words, though its brevity stems partly from under-specification rather than efficient editing.

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, but with 0% schema coverage the description should explain the cursor and account_id parameters. For a paginated list tool it leaves the agent guessing about filtering and paging.

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% and both parameters (cursor, account_id) are undocumented. The phrase 'for an account' loosely implies account_id, but the cursor/pagination mechanism and whether account_id is required or optional are never explained.

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

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

The description states a specific verb ('List') and resource ('alert policies') scoped to 'an account'. It is clear what the tool does, though it offers no differentiation from similarly-shaped list siblings like list_open_issues or list_deployments.

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

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

There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites, filters, or pagination conditions. An agent must infer all usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered elsewhere. The description adds only the ordering behavior ("newest first"); it says nothing about default result volume, the implicit time window, or pagination/truncation behavior an agent would want before relying on completeness.

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

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

Two sentences, zero filler, with the core operation front-loaded before the usage hint. Every clause 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 not be described. However, with four entirely undocumented parameters and only a vague "recent" scope, the description is thin for a filtering tool; an agent cannot tell what the default query actually returns.

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% across four parameters (limit, since, account_ids, entity_guid), so the description carries the full burden. It only implies "recent" via prose and never explains the since default of 7 days, the limit range of 1-200, or that account_ids/entity_guid filter scope, leaving all four parameters semantically thin.

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

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

The description states a specific verb and resource ("List recent deployments") plus a result-ordering detail ("newest first"), so the operation is unambiguous. It does not name a sibling to distinguish itself from, relying on the contextual hint about traces to imply its place in the workflow.

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

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

"Use this to check whether an incident lines up with a release before digging into traces" gives a concrete investigative trigger for calling the tool, which is good workflow context. It stops short of naming the alternative trace tools (get_trace) or stating when not to use it, so it lacks 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 already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds that returned conditions include their queries and thresholds, which is genuinely useful context, but says nothing about pagination behavior despite a cursor parameter.

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

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

Two short sentences, front-loaded with what the tool returns; nothing is redundant or padded.

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 explanation is not needed, and the annotations cover the safety profile. The gap is on the input side: with three parameters and 33% coverage, the description should have clarified cursor paging and account_id scoping.

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 only 33% (policy_id is documented, cursor and account_id are not), and the description mentions no parameters at all. It therefore fails to compensate for the undocumented cursor and account_id fields, leaving the agent to infer how pagination and account scoping 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 and resource: 'List NRQL alert conditions,' and adds scope detail ('including their queries and thresholds'). It is clearly separable from siblings like list_alert_policies or get_entity, though it never names an alternative to sharpen the distinction.

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 second sentence gives a rationale ('fastest way to reproduce what an alert saw at the time it fired'), which implies when the tool is useful, but it offers no explicit when-not guidance and no comparison against run_nrql or list_alert_policies.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive behavior, so the safety profile is covered. The description adds that the default scope is active issues and that results carry entity GUIDs, which is useful context. It stops short of describing pagination via cursor or result shape, so it goes slightly beyond the annotations but not richly.

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

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

Two short sentences, front-loaded with the core verb and default scope, then the payoff for using it. Every sentence earns its place, though the line-wrapping is awkward and the second sentence could be tighter.

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, and the annotations cover safety. The remaining gap is routing guidance versus sibling listers, but for a 4-parameter optional-args read tool the definition is otherwise complete enough to invoke correctly.

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

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

Schema coverage is 50%: priority and only_open are documented in the schema, while cursor and account_id are not. The description adds nothing about these parameters beyond restating the default active-only behavior that only_open already encodes. Baseline 3 is fair given the schema carries all the specific parameter documentation.

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

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

States a specific verb and resource: lists alert issues, defaulting to currently active ones. It distinguishes itself from generic query tools like run_nrql by naming 'alert issues' specifically, though it never explicitly contrasts with sibling listers such as list_alert_policies or get_recent_errors.

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 implies usage via 'the usual entry point for an on-call investigation,' which gives context for when to reach for it. However, it names no alternative and states no exclusion conditions, so an agent must infer that run_nrql or get_recent_errors are not the right first call. Implied usage only.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is well covered by structured data. The description adds useful context about what data is reachable (events, metrics, logs, spans) and the general-purpose fallback role. However, it doesn't add much beyond annotations about behavior like rate limits, account scoping defaults, or query timeout 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?

Three sentences, front-loaded with the core action and scope, followed by data-type coverage and the sibling-tool routing guidance. No waste, each sentence earns its place.

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

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

With an output schema present, the description needn't explain return values. Annotations cover safety and idempotence. The description covers purpose, scope, and sibling alternatives completely enough for an agent to invoke correctly. Nothing critical is missing.

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

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

Schema coverage is 100%, so all three parameters are fully documented in the schema, including 'SINCE and LIMIT are added when absent', account defaults, and timeout bounds. The description adds no additional parameter syntax or semantic details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource (run a NRQL query) and clarifies scope (one or more New Relic accounts). It names sibling tools (search_logs, get_trace, get_recent_errors) that it is adjacent to, so an agent can tell it apart from alternatives without opening schemas.

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

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

Explicitly says to prefer dedicated tools (search_logs, get_trace, get_recent_errors) when they fit, because those return tuned shapes. It frames this tool as the general-purpose fallback for anything stored as events, metrics, logs, or spans. This is clear when-to-use and when-to-prefer-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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds the useful behavioral trait that it polls until finish, which is genuinely beyond annotations. However, it omits auth requirements, timeout specifics, or return shape (though output schema exists). Given annotations carry safety, this is adequate but not rich.

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

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

Three short sentences, front-loaded with the primary action and scoping, then usage context, then the comparison to run_nrql. No waste or redundancy.

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

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

For an async query tool with annotations covering safety and an output schema, the description covers purpose, timeout behavior, and usage conditions well. The undocumented account_ids parameter and lack of explicit polling/timeout expectations leave minor gaps, but overall it is sufficiently complete.

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

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

Schema coverage is 50%; the 'query' param has a description in schema ('Long-running NRQL query') but 'account_ids' is undocumented in both schema and description. The description adds no parameter-specific detail. With partial coverage and description silence on account_ids, this is the baseline 3.

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

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

States a specific verb and resource ('Run a NRQL query') and adds qualifying scope ('that exceeds the synchronous timeout, polling until it finishes'). This distinguishes it from run_nrql by timeout/polling behavior, though it doesn't name the sibling explicitly in contrast terms. The purpose is clear but sibling differentiation is only implied.

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 condition for use ('wide time windows or heavy aggregations') and states it is 'slower than run_nrql, so it is not the default choice,' which effectively conveys when to prefer the alternative. Lacks an explicit 'avoid when' rule but provides strong context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description adds genuinely new chaining context beyond the annotations: the returned GUID is the key for get_entity, logs and alert lookups, which tells the agent how this call fits into a workflow.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the workflow hint second. Every clause carries information.

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

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

An output schema exists so return shape need not be described, and the description still supplies the one output detail that matters for chaining (the GUID). For a six-parameter, all-optional search tool with rich annotations, nothing essential 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 83% and the schema itself documents LIKE matching for name, exact tag semantics, cursor pagination and enum-like domain/entity_type values. The description only restates name/type/tag and adds nothing about the cursor, domain or account_id parameters, so baseline 3 applies.

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

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

States a specific verb (find) and resource (entities) and enumerates the concrete entity kinds (services, hosts, lambdas, browsers) plus the match keys (name, type, tag). The second sentence positions it against the sibling get_entity by explaining it is the entry point when only a name is known.

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 ('start here when you only know a service name') and names the downstream alternative (get_entity) that consumes its output, which is strong routing guidance. It does not state when *not* to use it (e.g. when a GUID or an NRQL query is already available).

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely useful behavior beyond that: results are ordered newest-first and credential-shaped values are masked server-side before returning. It stops short of describing pagination/limit behavior when more than 500 matches exist, which is the one remaining trait an agent would want.

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

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

Two short sentences, front-loaded with the core purpose, then the two behavioral facts. Every sentence earns its place with no 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 shape needn't be explained, and the description covers ordering plus the masking guarantee. It is nearly complete for an 8-param search tool, but omits filter-combination semantics and result-limit/truncation behavior, which matter for correct invocation.

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

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

Schema description coverage is 63%, and the description only restates the four already-documented filters (service, level, trace id, message) without adding format or semantics beyond the schema. It does not compensate for the undocumented parameters (account_ids, entity_guid, limit), and it never says whether multiple filters combine as AND or OR.

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

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

States a specific verb (search) and resource (logs) and enumerates the filter dimensions (service, level, trace id, message content), so an agent knows exactly what the tool does. It never distinguishes itself from the adjacent summarize_log_errors or get_recent_errors siblings, so it falls short of a 5.

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

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

The description only implies usage; it gives no when-to-use condition, no prerequisites, and names no alternatives. With summarize_log_errors and get_recent_errors in the sibling set, the agent gets no routing signal for when a raw search beats an aggregation tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds the aggregation-by-pattern behavior, which is genuinely useful, but says nothing about the default 1-hour window, result cap, or how grouping/counting is performed. With annotations carrying the safety burden, a 3 fits.

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

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

Two short sentences, zero waste, and the core behavior is front-loaded ahead of the disambiguation rule. Nothing here is padding.

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

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

An output schema exists, so return values need not be explained, and the routing rule is complete. However, the four undocumented parameters and their defaults (1 HOUR AGO, limit 20) leave the caller guessing about scope, which matters for a log-aggregation 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% across four parameters, so the schema contributes nothing about what since, limit, account_ids, or service_name mean or their defaults. The description mentions no parameters at all, so it fails to compensate for the coverage gap. An agent cannot learn the time-window or scoping semantics from either source.

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 ('Group error logs by message pattern') plus the outcome it produces ('show what is failing most'). This is clearly distinguishable from the sibling search_logs, which it names explicitly.

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

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

Gives an explicit routing rule: use this over search_logs when the question is 'what is broken' rather than 'show me this specific request'. The alternative and the condition that selects it are both stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by explaining that the tool returns the query as it would be sent, including automatically appended SINCE and LIMIT clauses, which is beyond what annotations 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?

The description is two efficiently structured sentences: the first front-loads the tool's purpose, and the second adds return-value context. There is no redundant or filler text.

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

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

Given the simple one-parameter input, rich annotations, and the existence of an output schema, the description is largely complete. It clearly states the tool's purpose and return behavior, though it could do more to guide when to use this tool versus the sibling execution tools like run_nrql.

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

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

The schema has 100% description coverage for the single query parameter, so the schema already documents its meaning. The description does not add any additional syntax or format details for the query parameter, making the baseline of 3 appropriate.

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

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

The description states a specific verb and resource: 'Check a NRQL query against the server guardrails without running it.' It also distinguishes this tool from execution tools like run_nrql by explicitly saying it works without running the query.

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

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

The phrase 'without running it' implies that this tool is for validation rather than execution, giving a clear contextual cue. However, it does not explicitly name alternatives such as run_nrql or state when validation should be preferred, leaving the agent to infer the usage scenario.

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