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

No annotations are provided, so the description carries the full burden. It discloses the content and the human-in-the-loop nature of the log, but never states that it is read-only, how far back the log goes, whether results are paginated, or whether it requires a trace_id. Meaningful behavioral traits beyond the payload are left unstated.

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

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

Two short sentences with zero filler: the first states what the log contains, the second states when to reach for it. Front-loaded and appropriately sized for a single-parameter read tool.

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

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

An output schema exists, so return values need not be described here. However, with no annotations and an undocumented optional trace_id, the description leaves the agent unsure whether a call returns the whole log or requires scoping, which is a real gap for an audit 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?

There is 1 parameter (trace_id) with 0% schema description coverage, and the description never mentions it. The phrase 'every approval/denial/edit' actually implies a full log, giving no hint that passing trace_id narrows scope or that omitting it returns everything.

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 resource (approval/denial/edit audit log) and enumerates its contents (decision, decider, rationale), so the agent knows exactly what is returned. It does not explicitly contrast itself with near-siblings like security_audit or failure_report, 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?

It gives concrete trigger phrasings ('why did the agent get to do X?', 'what was denied?'), which is clear when-to-use guidance. It stops short of naming an alternative tool or stating when NOT to use it, so no exclusion guidance is present.

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

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

No annotations exist, so the description carries the full behavioral burden. It usefully enumerates the comparison dimensions (latency, cost, tokens, tools, failures) but says nothing about cardinality limits, whether runs must be compatible, or any auth/rate constraints; with an output schema present, the return shape is covered elsewhere.

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 filler; the resource and the compared metrics come before anything else.

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

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

For a one-parameter read tool with an output schema, the description covers what the tool does but leaves usage conditions and constraints to inference. Adequate, not 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 0% and the single parameter is only titled 'Trace Ids'. The description's phrase 'trace-id prefixes' is the one piece of semantic information available, and it materially changes how the agent should populate the array (prefixes rather than exact ids).

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 ('compare') and resource ('trace-id prefixes') plus the exact metrics compared, so the agent knows what it produces. It does not differentiate itself from conceptually adjacent siblings like run_summary or tool_stats, which keeps it below 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?

There is no explicit when-to-use, when-not-to-use, or alternative named. 'Selected' hints that the caller supplies the set, but nothing tells the agent when comparison is preferable to run_summary or list_runs.

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

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

With no annotations provided, the description carries the full behavioral burden. It does add two genuinely useful traits not in any structured field – output is 'bounded' (limited in volume) and 'redacted' (tokens/PII stripped) – which is real context, but it omits whether this is a read-only operation, what auth is needed, and how the bound is enforced.

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 tightly-worded sentence with no filler; the scoping constraint ('bounded, redacted') is front-loaded before the resource. Efficient, though the extreme brevity contributes to the completeness gaps.

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 required. However, with zero parameter documentation, no usage guidance, and no annotations, the definition leaves an agent underspecified on how to scope or interpret the call despite the tool being relatively simple.

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% for both parameters. The description never mentions 'limit' or 'trace_id', so an agent gets no explanation of what trace_id filters on or how limit interacts with the 'bounded' claim. Only the vague word 'bounded' hints at the limit parameter.

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?

Specific verb (Show) plus a well-defined resource: tool/provider failures and their diagnostics. It reads clearly as a diagnostics tool, though it never distinguishes itself from siblings like security_audit or tool_stats that might also surface problem data.

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

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

The description gives no when-to-use guidance, no prerequisites, and never names an alternative among the many sibling tools (security_audit, tool_stats, recent_activity). The context of use must be inferred entirely from the tool 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?

With no annotations, the description carries the full burden, and it discloses almost nothing behavioral: no statement that this is read-only, no definition of 'recent', no ordering, pagination, or auth context. Only the implicit read-only nature of 'List' and the field list are offered.

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, no filler, with the core purpose front-loaded before the workflow 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-value explanation is not needed, and the trace_id workflow hint is useful. But for a tool with zero annotations and an undocumented limit parameter, the description leaves too much undefined (recency window, result count control) to be considered complete.

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

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

The single parameter (limit) has 0% schema description coverage, and the description never explains what limit does, its default, or maximum. The field list describes outputs, not parameters, so it does not compensate for the coverage 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 (List) and resource (recent agent runs) and enumerates the fields the agent will see (task, model, duration, tool use, human decisions, cost). It is clear against generic siblings, though it does not explicitly differentiate itself from close siblings like recent_activity or run_summary.

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

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

'Use first to find the trace_id for deeper inspection' gives a concrete workflow position and a reason to pick this tool over the deeper-inspection siblings. No explicit exclusions or named alternatives are given, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key polling/cursor model, which is genuinely useful behavioral context for an incremental-read tool. However it says nothing about what happens at end-of-stream, whether the cursor is mandatory, or how trace_id scopes results.

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

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

A single front-loaded sentence with zero waste: it leads with the operation and tacks on the usage condition. Nothing to trim.

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 the polling model is captured. But with 0% schema coverage and no annotations, the two unexplained parameters (limit, trace_id) leave the definition short of what an agent needs to call it correctly.

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

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

Schema description coverage is 0% and there are 3 parameters. The description explains the purpose of 'cursor' in the polling model but leaves 'limit' and 'trace_id' entirely undocumented in both schema and description, failing to compensate for the coverage 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 ('Poll newly written spans') plus a mechanism ('using a cursor'). The word 'newly' implicitly distinguishes it from the one-shot search_spans sibling, but no sibling is named, so differentiation is left to inference.

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?

'useful while an agent run is still active' gives a clear temporal context for when to reach for this tool, but it names no alternative (e.g., search_spans) and states no exclusions, so the agent must infer the boundary.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only, abbreviated result via 'compact summary', but says nothing about prefix ambiguity handling (what if the prefix matches several runs), permissions, or truncation 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?

A single tightly written sentence with zero filler and the resource stated first. It may be slightly too terse given the naming mismatch between 'run' and 'trace_id', 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?

An output schema exists, so return values need not be described, and a single-parameter tool is low complexity. Still missing is any when-to-use framing versus the eleven sibling tools and clarification of the run/trace_id relationship, which leaves the agent guessing at 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 coverage is 0%, so the description must compensate, and it does so on the one point that matters: trace_id accepts a prefix, not just an exact ID. That is genuinely non-obvious from the schema, though format, minimum length, and ambiguity behavior remain unstated.

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 (summary) and resource (one run), and the word 'compact' signals the output shape. It doesn't explicitly differentiate itself from siblings like compare_runs or list_runs, and it uses 'run' while the parameter is named trace_id, leaving a small terminology gap.

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 and no mention of alternatives such as compare_runs, list_runs, or span_tree. The only usable hint is the parenthetical about trace_id prefixes, which is a calling detail rather than usage guidance.

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

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

With no annotations, the description carries the full behavioral burden. It does usefully disclose the search substrate (span names and attributes, not span IDs or payloads), which goes beyond the schema, but it says nothing about case sensitivity, whether the search spans all runs or one, result limits, or ordering. It is a read-only search by implication only.

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 verb and resource front-loaded and the illustrative examples compactly bracketed at the end. No filler, no restatement of the tool name.

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

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

An output schema exists, so return values need not be explained, and the description correctly covers the core search semantics for a two-parameter tool. The unaddressed trace_id scoping is the only substantive hole for an agent deciding between a global and a trace-scoped search.

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 there are two parameters. The examples give real meaning to 'needle' (substring matched against names/attributes), but 'trace_id' — the parameter that scopes the search — is never mentioned, leaving a meaningful gap the schema does not fill.

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 — substring search over span names/attributes — and clarifies what a 'needle' can be with concrete examples (tool name, file path, 'denied'). It does not distinguish itself from sibling diagnostics like span_tree or failure_report, so an agent gets no routing comparison.

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

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

The examples describe what values to search for, not when to choose this tool over alternatives such as span_tree or failure_report. There is no when-to-use, when-not-to-use, or prerequisite guidance; the agent must infer the use case from the tool 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?

With no annotations, the description carries the full behavioral burden. 'Audit' implies a read-only inspection and it lists the evidence categories examined, which adds useful behavioral scope, but it does not explicitly state read-only safety, permissions, or side effects.

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 tightly written sentence, front-loaded with the verb and resource. Every word earns its place with no filler or repetition.

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

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

An output schema exists, so return values need not be explained, but the description omits usage context and parameter semantics for a two-parameter security tool. It leaves significant gaps for an agent to call it correctly in a broader toolkit.

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% for two parameters, yet the description adds no meaning for 'limit' or 'trace_id'. It does not explain default behavior, filtering, or how these parameters shape the audit.

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 ('Audit') and enumerates the resources audited (caller identity, tenant, server provenance, risk, approval evidence for tool calls). Clear enough to distinguish from generic tools, but it does not differentiate from the related sibling 'approval_log' or others.

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

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

No guidance on when to use this tool versus alternatives such as approval_log or failure_report. It describes what is audited but not the investigative context or exclusions that would tell an agent when this is the right call.

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

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

No annotations exist, so the description carries the full burden. It does disclose the key behavioral trait — trace_id is optional and omitting it searches across all runs — which is the main thing an agent needs to know. It says nothing about ordering direction, tie-breaking, limits, or cost of an all-runs scan, which are the remaining unknowns for an unannotated 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?

Three short sentences, zero filler: purpose first, then the use-case trigger, then the scoping rule. Every sentence adds information an agent would otherwise have to guess.

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

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

For a simple read-only query tool with an output schema present, the description covers purpose, trigger, and scoping, so return format need not be explained. The only remaining gap is a thin treatment of k, which is minor given the parameter is optional with a default.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It implicitly covers k through "Top-k" and explicitly explains trace_id by describing what happens when it is omitted. It never states what k means concretely, its default of 5, or that it bounds the result size, so the compensation is partial.

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+resource: it returns the top-k slowest spans. That is unambiguous and an agent can picture the result set. It does not, however, distinguish itself from adjacent siblings like span_tree or search_spans, so it stops short of a 5.

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

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

"Use for 'why was this run slow?'" gives a concrete trigger scenario, and "Omit trace_id to search all runs" tells the agent how to widen scope. There is no explicit exclusion or named alternative (e.g. span_tree for full hierarchy, search_spans for text search), so it is clear context without routing guidance.

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

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

No annotations are supplied, so the description carries the full behavioral burden, yet it discloses only that the result is nested and carries durations. It says nothing about read-only safety, whether trace_id must come from list_runs, output size for deep trees, or pagination/depth 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?

One front-loaded sentence with no filler; the resource and the notable payload trait (durations) come first. It is efficient, though the brevity is partly under-specification rather than tight 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 explained, but for a tool with no annotations the description leaves the agent without usage routing, the meaning/source of trace_id, or any scale caveat. It is thinner than a minimum-viable definition for a run-inspection tool with many 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?

The single required parameter trace_id has 0% schema description coverage and is never mentioned in the description. With only one parameter the ambiguous origin of the value (which sibling produces a trace_id) is the key semantic gap, and it is left entirely unresolved.

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 concrete resource and shape — a nested span tree of a run, including durations — which is more specific than a tautology and implicitly distinguishes it from flat siblings like search_spans and slowest_spans. It stops short of explicitly differentiating itself from run_summary or compare_runs.

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

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

"The shape of what the agent did" gestures at a use case but gives no explicit when-to-use, when-not-to-use, or named alternative among the eleven siblings. An agent must infer whether this replaces or complements run_summary and search_spans.

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

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

No annotations are provided, so the description carries the full behavioral burden and it discloses almost nothing. It does not state that this is a read-only query, what cost basis or currency is used, or whether the aggregate covers all time or a bounded window. For a metrics tool with zero annotation coverage this is a real gap.

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

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

Two sentences, no filler, and the default-behavior guidance is front-loaded as the second sentence right where the agent needs it. Nothing could be cut without losing information.

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

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

An output schema exists, so return-value shape is covered, and with one optional parameter the schema surface is small. Still, for a cost-reporting tool that aggregates across runs, the description omits the aggregation scope (all time? bounded?) and the read-only nature, leaving meaningful agent questions unanswered.

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 single optional trace_id parameter has only a bare type declaration, so the description is the sole source of meaning. It supplies exactly the key semantic: omit it to aggregate across all runs, provide it to scope to that trace. Only the accepted ID format is left unstated.

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?

"Token and cost totals" names both resources the tool returns (tokens and cost), which is specific enough to distinguish it from generic stats siblings like tool_stats or run_summary. It is a noun phrase rather than a verb+resource, and it does not explicitly contrast with any sibling, 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?

"Omit trace_id to aggregate across all runs" implicitly tells the agent the two usage modes (scoped to one trace vs. global), which is useful. However, it never says when to prefer this tool over tool_stats, run_summary, or compare_runs, so routing between siblings is left entirely 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?

No annotations are provided, so the description carries the full behavioral burden. It never states the aggregation window, whether results are global or scoped to a trace, what the sort order or tie-breaking is, or that the operation is read-only. Read-only can only be guessed from 'rank'.

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 sentence with the verb, resource, and ranking dimensions front-loaded. There is no filler, no restatement of the tool name, and every word 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 values need not be described. However, with three parameters at 0% description coverage and zero annotations, the definition is only minimally viable — an agent could call it with defaults but would not know how to scope or limit the query correctly.

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

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

Schema description coverage is 0% for three parameters. The description mentions no parameter at all: limit (result cap), trace_id (scope to one trace), and tool_name (restrict ranking to one tool) are undocumented in both schema and prose. 'Rank tools' loosely gestures at the tool dimension but does not explain that tool_name filters it.

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

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

Names a specific verb (rank) plus the resource (tools) and the four ranking dimensions (errors, denials, latency, call volume), so the agent knows exactly what comes back. It does not, however, distinguish itself from overlapping siblings like failure_report or slowest_spans, which cover adjacent slices of the same data.

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 purpose clause 'to find unhealthy integrations' implies a diagnostic use case, but there is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives such as failure_report for error detail or slowest_spans for latency detail. Usage is inferable but not guided.

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