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

Annotations already declare readOnlyHint=true and openWorldHint=true, and the description usefully adds the required permission, "Needs logs.read." It does not disclose aggregation semantics such as bucket behavior, group limits, or how the result is shaped, which would matter for an aggregation tool.

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

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

The description is two short sentences with no filler. The core operation is front-loaded, followed by a concrete endpoint and permission requirement.

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 six-parameter read-only aggregation tool with 83% schema description coverage, the description covers purpose, endpoint, and authorization. It is reasonably complete, though it could better explain how grouping and bucketing shape 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 high at 83%, so the schema already documents most parameters. The description only broadly mentions counting "over time and by attribute," which loosely maps to time_buckets/from_time/to_time and group_by without adding syntax or behavioral detail beyond the schema.

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

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

The description states a specific verb and resource: "Count log records over time and by attribute," and adds the endpoint. This clearly distinguishes an aggregation operation from raw log retrieval, though it does not explicitly name or differentiate from the closest sibling, search_logs.

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 "Count log records over time and by attribute" implies when to use it, and "Needs logs.read" gives a prerequisite. However, it does not say when to prefer it over search_logs or other log-related siblings, nor does it state any 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=true and openWorldHint=true, so the safety and external-interaction profile is covered. The description adds useful behavioral context by noting that secrets are excluded and that token scopes are actively probed.

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

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

The description is a single well-structured sentence that front-loads the primary purpose and includes the important caveat about secrets. It is appropriately sized for a zero-parameter diagnostic tool.

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

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

For a simple zero-parameter tool with read-only/open-world annotations and no output schema, the description is largely complete: it covers the main output content and the scope-probing behavior. It could be slightly richer about the returned format, but it is sufficient 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?

The tool takes zero parameters, so there are no parameter semantics to clarify. The baseline for a zero-parameter tool is 4, and nothing in the description introduces ambiguity.

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 specific actions and resources: showing active configuration without secrets and probing token scopes. It is clear what the tool does, though it does not explicitly distinguish itself from any sibling because no sibling appears to perform a similar connection/scope check.

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 explicit when-to-use or when-not-to-use guidance, but the description and tool name imply diagnostic usage for inspecting configuration and token-scope behavior. The implied context is adequate but not fully spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description usefully discloses that this is a multi-signal aggregate and that metrics are compared baseline-vs-recent and logs are grouped by signature, but it says nothing about cost/latency of a fan-out call, result volume, or the default window (only the schema reveals now-2h).

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 the verb first and each clause mapping to a distinct returned section; there is no filler. It is dense and list-like rather than scannable, which keeps it just below a 5.

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

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

With no output schema, the description carries the burden of describing returns and does so thoroughly for all six signals. Gaps are minor: the default 2h window, expected result volume, and any guidance on cost of a multi-signal fan-out are absent, but nothing essential to invoking 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 already 83%, so the baseline is 3; the description adds mapping value by tying 'recent deployments/config changes' to deployments_from, 'failure logs ... grouped by signature' to log_filter/log_limit, and 'problems in the window' to the from_time/to_time pair. That conceptual framing goes beyond the field-level schema text, though it offers no syntax or default guidance of its own.

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 ('Debug a service') and immediately enumerates the exact signals returned: failure rate, volume, response time baseline vs recent, grouped failure logs, deployments/config changes, problems, and callers/callees. This composite scope is clearly distinguishable from single-signal siblings like search_logs, list_problems, or query_metrics.

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

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

The enumeration of signals implies 'use this for a broad service-level health check', but the description never states when to prefer it over siblings such as investigate_problem (which sounds like an overlapping entry point) or when to drop down to search_logs/query_metrics directly. Usage is inferable but not explicit, and no exclusions or prerequisites are given.

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=true, so the safety profile is covered. The description does add the matching strategy ('exact first, then contains'), which is useful behavior beyond the annotations. However, it says nothing about result ordering, limits, or whether it can return multiple matches.

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 zero waste; the matching order is stated immediately. It is appropriately short for what it conveys, though brevity comes at the cost of the missing guidance noted elsewhere.

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

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

For a 2-parameter read tool with annotations and no output schema, this is borderline complete. It omits what a match looks like and how many results may come back, and it leaves the ambiguity against search_entities unresolved.

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%: entity_type is documented in the schema, but the required 'name' parameter has no schema description. The description does not compensate, failing to clarify whether 'name' is a display name fragment, exact value, or identifier, nor how entity_type narrows the search.

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) plus the matching key (display name). It does not distinguish itself from the closely named sibling search_entities, so an agent cannot tell them apart from the description alone.

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

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

No indication of when to use this versus search_entities or get_entity, all of which exist in the sibling list. Usage is only implied by the verb 'Find' and offers no exclusions or prerequisite 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=true and openWorldHint=true, so safety is covered. The description adds the useful fact that relationships (calls, runsOn) are part of the payload, but it does not disclose that relationships are time-windowed by from_time/to_time (default now-72h), nor what happens when the entity 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?

A single short sentence with no filler, and the key payload elements are front-loaded. It is arguably too terse rather than too long, but 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?

With no output schema, the description does carry the return-value burden and lists the main payload sections. However, it omits the meaningful time-window semantics that shape results and gives no guidance for the unknown-entity case, leaving real gaps for a 4-parameter 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 50%: entity_id and include_relationships have no schema descriptions, and the description only hints at relationships without explaining include_relationships. The from_time/to_time parameters go unmentioned in the description, so the reader must infer from defaults that the relationship graph is bounded by a time range.

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 the resource and enumerates what is returned (properties, tags, management zones, relationships), but the sentence has no verb and no explicit statement that it fetches a single entity by ID. It is distinguishable from search_entities/find_entity_by_name only by inference from the required entity_id parameter.

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 search_entities or find_entity_by_name, and no prerequisites. Nothing tells an agent that this is the follow-up call after resolving an entity name to an ID.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that the result includes all properties, but it does not mention error behavior, permissions, rate limits, or what 'all properties' entails.

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

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

The description is a single front-loaded sentence with no wasted prose. It is efficient, though the endpoint detail is technical rather than agent-oriented.

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

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

For a simple read-only lookup, the annotations and description together are minimally viable. However, the lack of an output schema and the undocumented event_id leave the agent to infer the return shape and parameter format.

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 schema only says event_id is a required string. The description's endpoint reference implies an ID path parameter but does not explain the expected format, source, or constraints for event_id.

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

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

The description clearly identifies the resource and cardinality: it returns one event with all properties, and even names the underlying GET endpoint. It does not explicitly contrast with the sibling list_events, but the singular scope is clear.

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 explicit guidance on when to use get_event versus list_events, search_logs, or other event-related siblings. The singular 'one event' only weakly implies usage when a specific event ID is already known.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds value by disclosing what the response contains (unit, dimensions, aggregations, transformations), which is useful since there is no output schema. It does not say what happens for an unknown metric_key, nor whether the key must come from list_metrics.

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 waste; the resource comes first and the returned facets follow. It is terse to the point of under-specification, but 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?

With no output schema, listing the descriptor's facets does real work in describing the return value. Still missing are the metric_key format/source and error behavior, which matter for a one-parameter lookup 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% and metric_key has no documentation anywhere. The phrase 'one metric' weakly implies the parameter is a single metric identifier, but the expected format (dotted name, ID, enum source) is left entirely undefined.

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

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

States a specific resource and scope: the full descriptor of a single metric, with the returned facets (unit, dimensions, aggregations, transformations) enumerated. It is clearly a metadata-lookup, distinct in spirit from list_metrics/query_metrics, but it never names or contrasts those siblings 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?

No when-to-use guidance, no prerequisites, and no mention of the obvious alternatives (list_metrics to discover keys, query_metrics to fetch values). The agent must infer that this is a pre-query metadata inspection step.

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=true, so the safety profile is covered; the description's contribution is naming the returned fields, which matters since there is no output schema. It does not disclose depth limits on 'recent comments' (how many, how recent), whether evidence/impacts are summarized subsets of the dedicated siblings, or what happens for an unknown problem id.

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?

One short, front-loaded line with no filler; every listed field signals content. It is terse rather than padded, which is the right trade-off for a simple getter, though the terseness edges toward under-specification.

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

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

For a read-only, single-parameter getter with no output schema, listing the returned content is the main thing an agent needs. The remaining gap is not stating how this relates to the evidence/impact/comment siblings, but the core call path is adequately covered.

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 a single parameter at 100% schema description coverage, the schema already documents that problem_id accepts an internal id or a display id such as P-12345. The description adds no format, resolution, or error semantics on top of that, so the baseline 3 applies.

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

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

The phrase 'Problem details' plus the enumerated fields (status, root-cause entity, evidence, impacts, comments) makes it clear this is a single-problem retrieval that bundles related sub-resources. However there is no verb and no explicit differentiation from siblings like get_problem_evidence, get_problem_impact, and list_problem_comments, which appear to return the same content the description claims to include.

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 call this versus get_problem_evidence, get_problem_impact, list_problem_comments, or list_problems. An agent cannot tell whether this tool is a lightweight summary or a full aggregate that makes the specialist siblings redundant.

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=true, so the safety profile is covered. The description adds the useful detail that results span events, metric change points, and transactions, but says nothing about result volume, ordering, or how limit applies.

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 compact sentence with the resource front-loaded and the payload kinds parenthesized. Nothing is wasted, though the brevity comes at the cost of missing 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?

For a read tool with no output schema and two undocumented parameters, the description should explain the shape of returned evidence and the effect of limit/root_cause_only. As written, an agent can call it but cannot predict or control what comes back.

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 only 33%: problem_id is documented, but limit and root_cause_only have no descriptions anywhere. The description never explains that root_cause_only narrows results to root-cause evidence or that limit caps returned items, leaving two of three parameters semantically opaque.

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 the specific resource (evidence for a given problem) and enumerates what it contains (events, metric change points, transactions), which distinguishes it reasonably from get_problem and get_problem_impact. It lacks an explicit verb and doesn't name a sibling to contrast with, so it falls just 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?

No guidance on when this tool should be used instead of get_problem, get_problem_impact, list_events, or investigate_problem. The reader must infer that this is a drill-down companion to get_problem from the name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds useful content scope — it discloses that the result spans root cause, entities, and impact dimensions (users, services, apps) — which is meaningful because there is no output schema. But it says nothing about cost, depth, traversal limits, or whether impact analysis is computed or pre-aggregated.

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 short fragment with zero padding, and the content itself is front-loaded. But its brevity comes from under-specification rather than discipline — there is not even a grammatical sentence stating the action, so the terseness is a deficit, not an asset.

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?

Absent an output schema, the description does the important work of listing the return contents (root cause, affected/impacted entities, impact analysis). For a single-param read correlated with get_problem and get_problem_evidence, however, it omits the routing guidance an agent needs to pick this tool over its close siblings.

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 one parameter at 100% schema coverage (including the P-12345 display-id example), the schema fully documents problem_id and the description need add nothing. The description does not mention the parameter at all, so it neither helps nor harms; baseline 3 applies.

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

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

The description names the resource (problem impact) and enumerates its contents — root cause, affected/impacted entities, impact analysis across users, services, and apps. However, it is a bare noun phrase with no verb, so it never actually states what the tool does (retrieve? compute? summarize?). An agent can infer the scope but not the action, and it is not differentiated from get_problem_evidence or investigate_problem.

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 about when to use this versus the many related siblings (get_problem, get_problem_evidence, investigate_problem, list_problems). No prerequisites, no exclusions, no mention that a problem_id is required. The agent must infer usage entirely from the name.

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=true, so the safety profile is covered. The description adds real value by enumerating returned content, but says nothing about behavior when the ID is unknown, whether remediation is static advice or live data, or any latency/scope constraints.

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 the resource front-loaded and no filler. It reads as a noun phrase fragment rather than a statement of action, which costs it a point, but nothing is wasted.

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

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

With no output schema, the description does partial duty by sketching the return contents. For a one-parameter read tool this is close to adequate, but the missing ID format and not-found behavior leave real gaps.

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

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

Schema description coverage is 0% and the description never mentions the single required parameter. It does not say whether security_problem_id is an opaque ID, a numeric key, or a name, so it fails to compensate 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?

The description names the resource ('one vulnerability') and the content the call returns (risk assessment, affected entities, remediation), which is specific enough to distinguish it from the plural sibling list_security_problems. It lacks an explicit verb and drifts between 'security problem' and 'vulnerability', but the intent is unambiguous.

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

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

There is no when-to-use guidance and no alternative named. The agent must infer on its own that list_security_problems should be used to discover IDs before calling 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 already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds that a single evaluated record (percentage, error budget, burn rate) is returned, which is useful context, but it is silent on how the from_time/to_time window affects the evaluation or what happens when they are empty.

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 short sentence with no padding, so nothing is wasted, but it is also unstructured and too terse to front-load any operational guidance beyond the returned fields.

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

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

No output schema exists and three parameters are undocumented, so the description must explain the evaluation window and default behavior and does not. For a tool whose entire value is a time-scoped evaluation, leaving the time semantics unaddressed is a material gap.

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

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

Schema description coverage is 0%, so the description carries the burden, yet it says nothing about slo_id, to_time, or from_time. The empty-string defaults and the fact that the time fields presumably bound the evaluation window are left 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 phrase names the resource (one SLO) and the payload (evaluated percentage, error budget, burn rate), which is more concrete than the sibling list_slos, but it is a bare noun phrase with no verb and never explicitly contrasts itself with the listing tool. An agent can infer retrieval, but the definition does not state the action.

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 call this versus list_slos or the problem/metric tools. The only implicit signal is 'One SLO' versus a list, and nothing says what prerequisites exist or when this is the wrong 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the single-trace scoping and the notable caveat that the Classic API v2 has no trace endpoint, but says nothing about result limits, pagination, or what happens when a trace id yields no logs.

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 scope stated up front and no filler. The second sentence is cryptic but does not bloat the definition.

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 four-parameter read tool with no output schema, the agent knows enough to pass a trace_id and get log lines back. Missing are the return shape characteristics (volume, ordering, empty results) and any note on how the default 24-hour window interacts with trace selection.

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

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

Schema description coverage is 100%, so all four parameters (trace_id, from_time, to_time, attribute) are already documented with defaults and formats. The description contributes nothing beyond the schema, which makes the baseline 3 correct here.

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

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

The phrase 'Log lines for one distributed trace / PurePath' names a specific resource (log lines) and a precise scope (a single trace), which separates it from the sibling search_logs without naming it. It is a noun phrase rather than a verb, but an agent can tell what it returns.

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 explicit when-to-use statement and no named alternative such as search_logs when a trace_id is unavailable. The required trace_id parameter implies the precondition, but the agent must infer it; the sentence about the Classic API v2 is an implementation remark, not usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description adds real value by disclosing what data gets gathered (change events in the lookback window, error logs grouped by signature, baseline vs during metrics) and what comes back (findings, Markdown summary, next steps). It does not mention cost, latency, or failure modes for an operation that fans out across several data sources.

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

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

Two sentences, front-loaded with the 'One-shot RCA' identity and then a compact enumeration of correlated sources; the return-value sentence is separated out cleanly. The middle clause list is dense but each element is meaningful 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?

With no output schema, the description correctly takes on return-value disclosure (findings, Markdown summary, next steps), and annotations cover the read-only profile. The remaining shortfall is guidance on when to choose this composite over the granular sibling tools, which matters given how many related tools exist.

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 75% (problem_id, log_filter, and lookback_minutes are documented; log_limit only has bounds and a default), so the schema does most of the work. The description adds nothing parameter-specific -- 'before the start' loosely maps to lookback_minutes, and 'grouped by signature' hints at log_filter behavior, but there is no explicit param guidance to compensate for the log_limit 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 ('One-shot RCA' that correlates root-cause entity, change events, error logs, and metrics for a problem), which is far more concrete than a bare name. It implicitly separates itself from granular siblings like get_problem_evidence or search_logs by enumerating everything it pulls together, but never names those siblings 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?

'One-shot RCA' and 'before vs during' imply this is the entry point for a full investigation, leaving the agent to infer that it should be called instead of chaining get_problem_evidence, search_logs and query_metrics manually. There is no explicit when-to-use/when-not guidance, no mention of cost or latency, and no named alternatives despite ten-plus relevant siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description usefully adds the required scope (events.read), but says nothing about result ordering, pagination semantics, or what happens when next_page_key is supplied.

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 does, then the permission requirement. Nothing is wasted, though it is arguably terse enough to leave gaps rather than being optimally structured.

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

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

With six optional parameters, no output schema, and annotations covering safety, the description is adequate but thin: it doesn't mention the default two-hour window, page size, or selector syntax, all of which an agent must discover from the schema.

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

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

Schema coverage is 83% and five of six parameters carry descriptions, including the time formats and the next_page_key caveat. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

Names a specific verb and resource ('List events') and enumerates the event kinds covered (deployments, config changes, restarts, anomalies). It is clearly distinguishable from the singular get_event sibling, though it doesn't say so explicitly.

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

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

The sentence 'Needs events.read' gives a concrete prerequisite for calling it, which is genuine usage guidance. However, it never states when to use this versus get_event (single event), list_problems, or search_logs, nor any exclusion conditions.

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=true, so the safety profile is covered. The description adds the endpoint path, which hints at the upstream API shape, but says nothing about result ordering, pagination behavior, or result limits beyond what the schema's page_size/next_page_key fields imply.

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

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

One front-loaded sentence with no filler. Appropriately sized for a simple list tool, though the endpoint parenthetical is marginally more useful to a developer than to an 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?

For a read-only four-parameter list tool with no output schema, the description tells the agent what comes back (keys, units, dimensions). What's missing is the routing information an agent needs given three metric-related siblings in the toolset.

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 75%, so text, next_page_key, and metric_selector are already documented with examples; page_size is self-explanatory via its min/max bounds. The description contributes no additional parameter meaning, which is the expected baseline 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 ('Find') and resource ('metric keys and their units and dimensions'), plus the underlying endpoint. An agent understands the operation, but the description never distinguishes it from the closely-named sibling query_metrics or get_metric_descriptor.

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

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

No guidance on when to use this versus query_metrics (which presumably fetches actual metric data) or get_metric_descriptor (which presumably returns details for one metric). The agent must infer the discovery-vs-query distinction from names alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered, but the description adds nothing beyond the raw endpoint. It says nothing about pagination behavior, default page size, or that next_page_key ignores other filters — all traits an agent would need.

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 a single short sentence with no filler, so it is concise in the literal sense. However, the terse restatement-plus-endpoint framing leaves the reader with too little to act on, making it under-specified rather than efficiently compressed.

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

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

For a paginated list tool with no output schema and only light annotations, the description should carry the burden of describing return shape and pagination mechanics. It provides neither, so an agent must reverse-engineer behavior from the schema and endpoint string alone.

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 only 67% and the description adds zero parameter meaning. page_size has no description at all (default 50, max 500), and the description doesn't clarify that problem_id accepts a display id like P-12345 or how next_page_key interacts with filtering.

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

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

The description names the resource (comments on a problem) and even the underlying endpoint, so the agent can tell it retrieves comments rather than problem metadata. But it is essentially a restatement of the tool name plus a URL path, with no verb of action (list/retrieve) and no differentiation from siblings like get_problem or get_problem_evidence.

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 over get_problem, get_problem_evidence, or investigate_problem. The endpoint path implies a read of a sub-resource, but no conditions, prerequisites, or alternatives are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered; the description adds real value by naming the required scope ('Needs problems.read'), which the agent needs for auth planning. It says nothing about the default 24-hour window, result volume, or pagination behavior, so it only partially fills the behavioral gaps.

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 brief sentences, endpoint and permission front-loaded, with no filler. Nothing in the text is redundant with the schema.

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

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

For a 7-parameter, no-output-schema listing tool, the definition covers the endpoint and auth scope but omits the implicit time-window default and the pagination model that materially change what comes back. The rich schema descriptions carry most of the burden, so it is adequate rather than 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 86%, with sort, time range, selectors, and next_page_key all documented inline, so the baseline is 3. The description adds no parameter meaning whatsoever, notably omitting the impactful default of a trailing 24-hour time window.

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 problems') and maps it to the underlying endpoint GET /api/v2/problems, which is more than a name restatement. It does not, however, distinguish itself from the sibling list_security_problems, which is also a 'list problems' operation, leaving a small ambiguity an agent must resolve by name alone.

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 get_problem, investigate_problem, or list_security_problems. The only context is the permission requirement, which tells the agent it can run it but not when it should.

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 and openWorldHint; the description adds the required OAuth scope, which is useful context beyond annotations. It does not disclose pagination behavior, that next_page_key silently ignores the other filters, or the 500-item page cap.

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 endpoint, with the auth requirement second. Efficient, though the extreme terseness leaves obvious gaps for a six-parameter paginated 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?

No output schema exists, so the description would ideally explain the returned shape and pagination flow (nextPageKey, page_size default 50). For a six-param listing tool with hidden defaults like from_time=now-30d, the definition is only minimally sufficient.

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

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

Schema coverage is 67% and the description says nothing about any of the six parameters. The selector syntax and time formats are documented in the schema, so the baseline 3 applies; the undocumented sort and page_size are at least constrained by schema defaults and min/max.

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 vulnerabilities") and pins the exact endpoint GET /api/v2/securityProblems, so it is distinguishable from list_problems and get_security_problem. It stops short of explicitly naming the sibling used for a single vulnerability.

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?

Adds the prerequisite "Needs securityProblems.read", which is genuine invocation guidance. However it never says when to prefer this over get_security_problem or list_problems, nor what the default 30-day window implies about 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 declare readOnlyHint and openWorldHint, so the safety profile is covered; the description adds value by disclosing the required scope (slo.read) and what the payload contains (status and error budget). It omits pagination behavior, which matters for a listing tool with next_page_key, keeping it below 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?

Two compact sentences, front-loaded with the action and the returned content. The '(GET /api/v2/slo)' fragment is mildly redundant but arguably useful for agents mapping to the underlying API.

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 6-parameter, read-only listing tool with no output schema, the description covers purpose, return content and auth scope but leaves pagination, the meaning of 'status' (current vs evaluated over a window), and the evaluate/to_time interaction unexplained. Adequate but with clear gaps.

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

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

The description mentions no parameters at all, while schema coverage is only 67% — evaluate has no description in the schema, and page_size, next_page_key and slo_selector syntax are only partly documented there. With a meaningful share of parameters undocumented, the description needed to compensate and does 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?

States a specific verb and resource (list SLOs) plus what each entry carries (status and error budget), which an agent can distinguish from the singular sibling get_slo. It does not explicitly name get_slo as the single-SLO alternative, but the list/get split is implied by the verb.

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?

'Needs slo.read' is a concrete prerequisite that tells the agent whether it can call the tool at all. However, there is no guidance on when to prefer list_slos over get_slo or how this relates to SLO-related siblings; usage is only implied.

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

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

Annotations already cover read-only/open-world safety, and the description adds real context on top: the underlying GET endpoint, the required metrics.read permission, and the shape of the aggregation returned. It stops short of covering pagination, rate limits, or what happens when a selector matches nothing.

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

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

Two compact sentences, front-loaded with the action and the result shape, then the permission requirement. No filler and nothing repeated from the schema.

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

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

For a 7-parameter read tool with full schema coverage, the description supplies what structured fields cannot: the permission prerequisite and the per-series aggregate return format despite there being no output schema. Missing only edge-case behavior such as empty result sets or large-range limits.

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

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

Schema description coverage is 100%, so every parameter including selector syntax examples is already documented, making 3 the baseline. The description's only added semantic is that results are per-series aggregates, which loosely explains the include_datapoints summary-vs-full behavior already described in the schema.

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

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

States a specific verb and resource (query metric data) and pins down the return shape as per-series min/max/avg/last, which separates it from list_metrics/get_metric_descriptor in the sibling set. It never names those alternatives explicitly, so differentiation is inferred rather than stated.

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

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

Usage is implied by 'Query metric data' plus the summary statistics, and the 'Needs metrics.read' clause flags a prerequisite. There is no explicit when-to-use/when-not guidance and no mention of list_metrics or get_metric_descriptor as the alternatives for descriptor discovery versus data retrieval.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the required scope ('entities.read') and the API path, which is genuine auth context, but says nothing about pagination behavior or result shape.

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

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

Two compact sentences with zero padding, and the core action is front-loaded. The endpoint reference is slightly incidental but harmless.

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

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

Covers purpose, scope requirement, and the endpoint for a 6-param read tool. However, with no output schema, the description gives no hint of what a result contains (entities, cursor), leaving the agent to infer the return contract.

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 description adds nothing beyond restating that a selector is required. The selector syntax and the next_page_key ignore-other-filters behavior are already in the schema, so baseline 3 is appropriate.

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

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

States a specific verb (Search) and resource (monitored entities), and names the mechanism (selector) plus the underlying endpoint. It is clear what the tool does, though it does not explicitly differentiate from siblings like find_entity_by_name or get_entity.

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 permission requirement ('Needs entities.read') is useful, and searching by selector implies discovery use. But there is no guidance on when to use this versus find_entity_by_name or get_entity, which are the obvious alternatives for entity lookup.

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=true, and the description usefully adds the required OAuth scope. Beyond that it discloses nothing extra: no mention of the default 2-hour window, pagination via next_slice_key, result caps, or rate limits.

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

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

Two short sentences, both carrying information, with the operation stated first. Nothing is padded, though the brevity leaves gaps that could have been filled without bloat.

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

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

With six optional parameters, no output schema, and a pagination token whose reuse semantics matter, the description should say more about paging, default time behavior, and how results relate to sibling tools. The scope hint is the only context offered.

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%, so the schema itself already documents sort, query, time bounds, and next_slice_key with examples. The description adds no parameter meaning whatsoever, which is acceptable but no better than baseline.

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

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

States a specific verb and resource ("Search log records") and even names the backing endpoint, so the agent knows exactly what operation this is. It does not, however, distinguish itself from siblings like aggregate_logs or get_trace_logs, which also read logs and could be confused with a plain 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?

"Needs scope logs.read" is an auth prerequisite rather than usage guidance. There is no statement about when to prefer this over aggregate_logs, get_trace_logs, or investigate_problem, and no exclusions or querying-context advice.

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