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

Explicitly discloses side effects beyond the annotations: it enables dart:io HTTP timeline logging on the app and adds the GC stream to the VM timeline recorder, and it states existing recorded streams are preserved rather than replaced. This clarifies the non-read-only (readOnlyHint=false) and idempotent (idempotentHint=true) hints with concrete mechanism.

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

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

Front-loaded with the action and payoff, then the parameter source, then the mutation caveat. Information-dense and mostly waste-free, though the parenthetical stream-logging detail is slightly wordy for an agent that mainly needs the URI.

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 tool with no output schema, it covers what the tool does, what it changes on the target app, and how to obtain the URI. It omits session lifecycle details (whether repeated connects stack sessions, how to disconnect), which are minor but would complete the picture.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real value by telling the agent where the URI comes from (the `flutter run` output line) and that both ws:// and http:// forms are accepted. That sourcing guidance is not present in the schema example.

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 (connect) plus resource (Flutter app's Dart VM Service) and the immediate consequence (start collecting runtime data). Clearly distinguishable from sibling readers like get_logs, get_timeline, or runtime_status, which presume an already-connected session.

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

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

Gives the precondition for the required parameter precisely: pass the ws:// or http:// URI printed by `flutter run`, quoting the exact line to look for. It does not, however, name alternatives or state when *not* to call it (e.g., when a session is already connected), so it stops short of full routing guidance.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses a great deal: the shape of findings (evidence ids, strength, fix), the 'healthy' and 'unknown' sentinel states, explicit blind spots (no CPU sampling, no widget rebuild counts), and the caveat that GC correlation strength is bounded by frame coverage of the window. This is unusually rich behavioral disclosure that annotations cannot carry.

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

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

It is a long description, but it is front-loaded with the core proposition ('why... not just how much') and every subsequent clause adds distinct information about outputs, states, or limits. Density is high enough that the length is mostly justified, though it could be trimmed slightly.

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

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

There is no output schema, so the description bears full responsibility for describing returns, and it does: percentiles, build-vs-raster split, correlated findings with evidence ids/strength/fix, plus healthy/unknown semantics and explicit limitations. An agent has everything it needs to interpret results.

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

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

The tool takes zero parameters, so the baseline of 4 applies and there is no parameter semantics to clarify. Nothing in the description contradicts or undermines this.

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 and sharpens the scope with the contrast 'why the app is janky, not just how much,' which implicitly separates it from raw measurement tools like get_frames. It does not name any sibling explicitly, so an agent must infer the boundary from the 'why vs how much' framing rather than a direct reference.

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 context is clear: reach for this when you need causes rather than magnitudes, and the 'healthy'/'unknown' states tell the caller when the output is trustworthy versus noise. There are no explicit exclusions or named alternatives, so routing against diagnose_runtime or get_frames is left to inference.

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

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

The annotations already declare this as read-only, idempotent, non-destructive, and closed-world, so safety behavior is covered. The description adds substantial behavioral context beyond annotations: returned fields, diagnosed/unknown status, the 70% confidence cutoff, confidence breakdown, limitations, alternative causes, timeline, and recommended fixes. There is no contradiction with annotations.

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

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

The purpose is front-loaded in the first sentence, followed by a dense but useful inventory of return behavior and the unknown-status threshold. No sentence is filler, and the length is justified because no output schema exists.

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?

Because there is no output schema, the description's detailed return-value explanation is essential and largely complete for a zero-parameter diagnostic tool. It still omits routing guidance versus sibling diagnostic tools and any precondition about how evidence must be captured, keeping it short of 5.

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 has zero parameters, so there are no parameter semantics for the schema or description to document. The baseline for a zero-parameter tool is 4, and the description appropriately avoids inventing parameter guidance.

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 action (correlate captured runtime evidence into a root-cause diagnosis) and resource, going beyond merely restating the title. However, it does not distinguish itself from sibling diagnostic tools such as diagnose_performance or explain_diagnosis, so it is clear but not sibling-differentiating.

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 explicit when-to-use, prerequisite, or alternative guidance. It implies the tool is used after runtime evidence has been captured, but does not say when to choose it over diagnose_performance, explain_diagnosis, or the lower-level evidence tools.

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

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

Annotations declare destructiveHint=false and idempotentHint=true but leave readOnlyHint=false unexplained; the description resolves that by stating 'Read-only by default' and disclosing the mutation's side effects — adbd restarts on the device, the cable is needed once, and `adb usb` reverses it. That is material behavior beyond what the annotations convey, and it does not contradict them.

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

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

Three sentences, front-loaded with the read-only report behavior before the promote path and platform caveats. Dense but essentially waste-free; the clause about the VM Service tunnel is justification, not filler, though the sentence count could be trimmed slightly.

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 tool with no output schema and an optional state-changing mode, the description covers the return signal (adbAvailable:false on unsupported platforms), the mutation's preconditions and reversibility, and the default safety posture. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it explains that promote performs `adb tcpip`/`adb connect`, and that serial selects which USB device to promote. Port is left to the schema, which fully documents it, so this is a modest but genuine uplift.

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 ('Report Android device transports and recommend one, preferring wireless') and then scopes the mutation mode ('With promote:true it runs adb tcpip and adb connect'). No sibling tool overlaps this behavior, so an agent can route to it unambiguously.

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

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

Explicitly frames when the tool matters (a `flutter run` on USB loses its VM Service tunnel when the cable moves), what the default is (read-only), when to escalate (promote:true), when it does NOT apply (iOS, desktop, web), and how to undo it ('reversible with `adb usb`'). This is when/when-not/alternative guidance in full.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral content beyond that — the return surface (claim, resolved events, timeline, competing explanations, missing evidence, confidence breakdown) and the constraint against fabricating reasoning. It doesn't address latency or cost, but for a read-only explainer this is solid.

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

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

Front-loaded with the core purpose ('Why diagnose_runtime reached its conclusion'), followed by a dense but purposeful enumeration of returned content and one usage sentence. The list is long but every element earns its place given there is no output schema; no filler.

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

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

There is no output schema, so the description must carry the return-value burden, and it does so thoroughly by enumerating the claim, resolved evidence, timeline, competing explanations, gaps, and confidence breakdown. Combined with zero parameters and clear annotations, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate at the parameter level.

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 verb (explain) and resource (the diagnosis produced by diagnose_runtime), and it explicitly frames the tool as the 'why' counterpart to diagnose_runtime. An agent can distinguish it from siblings like diagnose_runtime or get_timeline without opening any schema.

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

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

It gives a clear triggering condition: 'Use to answer "why do you think that" without inventing reasoning,' which implies invocation after a diagnose_runtime conclusion. It doesn't explicitly name alternatives or exclusions, but the usage context is unambiguous.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes further with measured payload sizes (36kB vs 247kB, ~62,000 tokens) and the fact that credentials are redacted at capture. These are behavioral traits an agent could not derive from the structured fields.

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

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

Front-loaded with the artifact definition, then mode semantics, then the cost rationale. Every sentence earns its place; the size/token figures and redaction note are load-bearing, not padding.

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

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

With no output schema, the description carries the burden of describing the return value and does so thoroughly (contents of the artifact, both mode shapes, size implications). Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the enum already defines both modes, so the baseline is 3. The description nonetheless adds real decision-relevant meaning beyond the schema: the measured size gap between modes and the practical implication (inline vs file), enabling a smarter mode choice.

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

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

States a specific verb+resource ('export the whole session as one versioned JSON artifact') and enumerates exactly what the artifact contains: metadata, per-collector health, retention, captured events, and every diagnosis category. This distinguishes it from the sibling tools that each return one slice (get_logs, get_frames, diagnose_runtime, etc.).

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

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

Explicitly routes between the two modes with concrete conditions: 'brief' for the smallest sufficient context, 'full' for bug reports, offline analysis, or a regression fixture. It even prescribes behavior ('treat full as something to write to a file rather than read inline'), which is exactly the when-to-use guidance an agent needs.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, non-open-world), so the bar is lowered. The description adds genuine value beyond that by disclosing what information the report exposes — including per-tool safety classes and current redaction/retention settings — which tells the agent this is a discovery/authorization-check step. It does not describe output format or size, but the content disclosure is substantive.

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 noun phrase 'Machine-readable capability report' and the contents listed before the call-to-action. Dense but every clause carries information; the mid-sentence inventory is slightly list-heavy but not padded.

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

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

There is no output schema, so the description must convey what comes back — and it does, specifying collectors, tool safety classes, observability boundaries, and configuration. With zero parameters and annotations covering safety, nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies a parameterless, whole-server query and adds no misleading parameter guidance.

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 artifact (a machine-readable capability report) and enumerates its contents: active collectors, per-tool safety class, observability limits, and redaction/dashboard/retention configuration. No sibling tool in the list returns this meta-level inventory, so an agent can distinguish it immediately from the diagnostic getters (get_logs, get_frames, diagnose_runtime, etc.).

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 an explicit trigger condition: 'Read this before attempting an operation that may not be supported.' That is clear when-to-use guidance. It stops short of naming a specific alternative tool or a when-not-to-use case, but for a self-describing capability tool no meaningful alternative exists.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description usefully adds what the dashboard displays (logs, network, exceptions, frames, memory), but says nothing beyond that — no note on URL lifetime, whether it requires a running session, or what to do if it's unavailable.

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

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

Two tight sentences with the return value front-loaded and the parenthetical describing the dashboard placed immediately after the noun. 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?

For a zero-parameter, read-only URL getter with full annotation coverage and no output schema, the description is essentially complete. Minor omissions (URL validity window, any prerequisite session state) keep it from a 5.

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

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

Zero parameters, so there is no parameter semantics to convey; the baseline for a no-arg tool is 4. The description neither needs to nor does add parameter meaning.

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

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

States a specific verb+resource ("Return the URL of the live Realtime Runtime Dashboard") and characterizes the resource as a browser UI streaming logs, network, exceptions, frames & memory, which implicitly differentiates it from the individual get_logs/get_network/get_memory siblings. It stops short of explicitly routing the agent to those alternatives.

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?

"Open it in a browser to watch the app alongside the AI" gives a clear intended action, so usage is implied rather than absent. However, it never states when to prefer this aggregate view over the granular siblings, nor any when-not condition.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds real behavioral value beyond that: result ordering (most recent first) and the specific content of each entry, including the data.stackTrace path where a stack trace may be absent.

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

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

Two tight sentences: the first front-loads scope and ordering, the second enumerates returned fields. No filler, though the second sentence packs several clauses together.

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 usefully enumerates the returned fields and the optional stack trace, and annotations cover the safety profile. Still missing is any mention of the limit parameter's effect or whether results are truncated, which would matter for a list-returning 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 one parameter (limit, default 20, max 200) with 0% schema description coverage, and the description never mentions it or what capping the list does. The name and bounds are largely self-explanatory, so this is adequate but adds no meaning 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?

States a specific resource (Flutter framework errors and unhandled VM exceptions) and ordering (most recent first), which lets an agent distinguish it from generic log tools. It does not name a sibling such as get_logs to sharpen the boundary, so it falls short of a 5.

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

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

The scope wording ('framework errors and unhandled VM exceptions') implies when this tool is the right one, but there is no explicit when-to-use, when-not, or alternative named among the many siblings (get_logs, runtime_health, diagnose_runtime). Usage is left to inference.

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

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

Annotations already cover the read-only, idempotent safety profile, so the description adds valuable behavioral context: the default frame budget of 16.67ms is an assumption because the VM Service does not report refresh rate, and it can be overridden via FLUTTER_LAMP_FRAME_BUDGET_MS. It does not describe return format, but that is a minor gap against otherwise strong disclosure.

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

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

The description is three sentences, front-loaded with the core purpose and then the onlyJanky nuance and override instruction. Every sentence adds useful information with no redundancy.

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

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

For a simple query tool with annotation coverage, the description is adequate but leaves gaps: it does not explain the limit parameter, what fields the timings contain, or whether results are paginated. It also gives no tool-selection context among related performance tools.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It fully explains onlyJanky (filters to frames over the frame budget, default budget, env override) but completely omits the limit parameter, leaving half the parameters undocumented beyond their types and defaults.

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 the resource ('Frame build/raster timings') with an implied retrieval verb, so an agent can tell what is returned. It does not differentiate from siblings like get_timeline or diagnose_performance, but the purpose 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?

The description gives guidance only for the onlyJanky parameter, not for when to use this tool versus alternatives such as get_timeline or diagnose_performance. No explicit context or exclusions for tool selection are provided.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful ordering behavior ('most recent first') and the source scope, but says nothing about the default limit (50), truncation, or whether results are capped/paginated. Adds some value beyond annotations but leaves 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?

One tight sentence that front-loads the content sources and ends with the ordering guarantee. Every clause earns its place with no filler.

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

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

For a 5-parameter read-only tool with no output schema, the description omits return shape, default limit behavior, and pagination/truncation semantics that an agent needs to call it correctly. The annotations cover safety, but the operational gaps remain, leaving it only minimally adequate.

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 80%, so the schema already documents source, sinceMs, contains, and minSeverity. The description's mention of Stdout/Stderr/Logging loosely maps to the source enum but adds no syntax or format detail for limit or the filters. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb+resource ('get_logs') and names the exact content it returns: Console output (Stdout/Stderr) and dart:developer logging. The 'most recent first' clause pins down ordering. It doesn't explicitly contrast with siblings like get_exceptions or get_network, but the log-source enumeration makes the domain 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?

The description gives no when-to-use guidance, no prerequisites, and no alternatives. An agent must infer that this is for raw console/developer output versus get_exceptions for crashes or get_network for traffic. There is no explicit routing signal.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description adds genuinely new context by disclosing a side effect the annotations do not surface — that each call records a snapshot into runtime history. It does not explain retention or snapshot cost, but this is meaningful added behavior.

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

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

Two sentences, no filler, and the primary purpose is front-loaded ahead of the less-obvious snapshot side effect. Every clause carries information.

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

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

With no parameters and no output schema, the description must stand in for the return value, and it does so by listing the metric components and their unit. The snapshot-to-history behavior is stated but its semantics (how much history, whether it affects later queries) are left open.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter discussion, and the schema (100% coverage) is trivially complete.

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 precise resource (Dart heap usage for the main isolate) and enumerates the sub-metrics returned (heap in use, capacity, external/native memory) with units. An agent can distinguish this from siblings like get_logs or runtime_status without opening a schema.

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

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

There is no statement of when to call this versus alternatives such as runtime_status, runtime_health, or diagnose_performance. The description explains what comes back but leaves the selection decision 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?

Annotations already declare readOnly/ idempotent/ non-destructive, so safety is covered. The description adds genuinely useful behavioral context: network attribution is by overlap, and a request spanning a route change counts for both routes. That is real beyond-annotation value, though return shape and ordering are left implicit.

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 front-loaded sentences: the first defines the artifact and its fields, the second gives usage. Both sentences earn their place with no filler.

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

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

With no output schema, the description correctly explains what comes back (route transitions plus attributed exceptions, failed requests, and janky frames). It covers the key attribution caveat. Minor gap: no mention of ordering, time window, or what 'recent' means, but it is largely 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 100% and the single 'limit' parameter is fully documented there (default 20, max 100, min >0). The description adds nothing about the parameter, so baseline 3 applies.

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

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

States a specific resource (route history: current route + recent transitions) and enriches it with what each entry carries (durations, exceptions, failed requests, janky frames). This clearly distinguishes it from siblings like get_network or get_timeline, which cover other data planes.

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

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

Gives an explicit use case ('which screen is broken') and a scoping role ('scope other evidence to a screen'), which tells the agent when to reach for this tool. It does not name alternatives (e.g., get_timeline) or exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: it fetches a fresh profile on demand (a live capture, not a passive read of cached state) and returns only completed requests, most recent first. The main gap is that it never mentions the default page size or that only a bounded window of requests is returned.

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

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

Two tight sentences, front-loaded with what the data is and where it comes from, then the fetch/return behavior. No filler, no repetition of the title, 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?

For a read-only inspector with annotations covering safety and no output schema, the description supplies the essentials: data source, on-demand capture, and result ordering/filtering. It stops short of sketching what a returned request record looks like or how the limit bounds the result set, which an agent would want given the absent output schema.

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

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

There is one parameter (limit) and schema description coverage is 0% – the schema supplies type, default 30, and max 200 but no explanation of what is being limited. The description never mentions limit at all, so it fails to compensate for the coverage gap. The name is largely self-evident, which keeps this above 1, but the description contributes nothing 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 description names a specific resource (HTTP requests/responses) and discloses the capture mechanism (dart:io profiling, covering Dio & package:http), which makes the tool's data source unambiguous. It does not explicitly distinguish itself from siblings like get_logs or get_timeline, but the domain is clear enough to select it confidently.

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 rather than stated: an agent can infer this is the tool to call when it needs network traffic, but there is no 'use this when / instead of X' guidance and no mention of prerequisites or timing relative to other diagnostics. Adequate but leaves routing to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description nonetheless adds real context beyond them: a debug build with widget creation tracking is required, and the tool reports why it is empty otherwise — a genuine prerequisite and failure-mode disclosure.

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

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

Three tight sentences, front-loaded with the core purpose, then usage, then the prerequisite. Every sentence carries information; nothing is padded.

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

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

For a single-parameter diagnostic tool with no output schema, the description explains what is returned (widget names, file/line, ranked), the scenario it answers, and the empty-result condition. Nothing an agent needs to call it correctly appears to be 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?

With a single parameter at 100% schema description coverage, the schema already documents 'limit' and its bounds. The description adds no meaning about the parameter, so the baseline of 3 applies.

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

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

States a specific verb and resource ('which widgets are rebuilding and how often') and pins down the output resolution (widget name, file, line) plus the ranking rule (own code above package code). This is clearly distinguishable from siblings like get_widget_tree or diagnose_performance, which cover different concerns.

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

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

Gives concrete usage scenarios ('why is this screen slow to build', finding needless rebuilds), which tells the agent when to reach for it. It does not, however, name alternative tools (e.g. diagnose_performance, get_timeline) or state when this is the wrong choice, so routing is not fully closed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the selection must come from 'select widget mode', and the result is null when nothing is selected.

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

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

Two tight sentences with zero waste. The primary identity ('what is returned') is front-loaded, and the null fallback follows immediately.

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

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

With no output schema, the description correctly carries the return-value burden by documenting the null case. It slightly under-specifies the shape of a returned widget (id, node, properties), but for a zero-parameter read tool this is close to 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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; no parameter semantics are needed or missing.

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

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

Names a specific verb+resource ('the widget currently selected') and identifies its source (Flutter Inspector select widget mode), so the agent knows exactly what it retrieves. It does not explicitly contrast with the sibling get_widget_tree, though the distinction is inferable from 'selected' vs. tree-wide.

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

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

Usage is implied by the 'select widget mode' reference and the null case, telling the agent this only works when the user has an active selection. There is no explicit guidance on when to prefer this over get_widget_tree.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds substantial non-obvious context: Riverpod emits an opaque buffer offset and provider emits an element id, neither resolvable to a provider name; counts are event notifications rather than transition counts, so one state change in a heavy tree yields many events; and stock Bloc posts nothing. These caveats materially change how an agent should interpret the numbers.

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

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

Three dense sentences, each carrying distinct information, with the primary purpose front-loaded before the get_rebuilds pairing and the interpretation caveats. The later sentences are long but every clause earns its place; 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?

There is no output schema, so the description must convey what comes back, and it does describe the shape at a high level (counts and timing, per-bucket busiest seconds) plus the key interpretive traps. It could be slightly more explicit about the return structure, but it covers what an agent needs to interpret results correctly.

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

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

Schema description coverage is 100% and the single 'buckets' parameter is already documented in the schema with its default, maximum, and meaning. The description adds no further syntax, units, or semantics for it, 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 description states a specific resource and measurement ('how much state-management activity the app is doing and when, plus how often build-heavy frames coincide with it'), which is far more precise than the tool name alone. It distinguishes itself from siblings by naming get_rebuilds as the complementary tool rather than a substitute.

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 an explicit usage context: pair with get_rebuilds to answer 'is this rebuild storm driven by state churn.' That is a clear condition that routes the agent to the right combination of tools. It stops short of stating when not to use this tool or what other diagnostic siblings might supersede it.

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

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

Annotations only say readOnlyHint=false; the description goes further and explains that recordFrom=true mutates the VM's recording configuration and enables specific Dart/GC/Compiler/Embedder streams. It also discloses the recorderLagMs/stalled failure mode where the recorder can stall permanently and still report streams as recorded, which is behavior no annotation conveys.

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

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

Front-loaded with the returned resource and ordering, then the recording prerequisite, then the result caveat. Every sentence carries needed information, though the final sentence is dense and would benefit from being split.

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

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

With no output schema, the description carries the return-value burden and does name specific result fields (recorderLagMs, stalled) and warns events may be historical. It stops short of stating what is returned when recording was never enabled (empty vs. error), which is the main remaining gap.

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

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

Schema coverage is 50%. recordFrom is richly explained (which streams it turns on, and that it is not read-only), adding value beyond the schema, but the `limit` parameter is never mentioned, so its semantics (cap of 200, default 50) rest entirely on 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 names a precise resource (VM timeline trace events) and enumerates the event classes returned (build/paint/layout/GC/etc.) plus ordering (most recent first). This clearly distinguishes it from siblings like get_logs, get_frames, get_memory, and get_rebuilds.

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

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

It states the prerequisite explicitly: recording must be enabled via recordFrom=true and the activity reproduced before events appear. It does not name alternative tools (e.g., get_logs or get_frames) for adjacent diagnostic needs, so the when-not-to-use side is absent.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds that this is a 'summary' tree of a 'running app'—implying an attached session and truncated detail—but does not say what is omitted, whether it requires a live connection, or how large trees are handled. Useful but modest added context.

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

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

Two short sentences, front-loaded with what the tool returns, followed by when to reach for it. No filler or redundancy.

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

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

No output schema exists, so the description carries the return-value burden; 'summary tree from the Flutter Inspector' does convey the shape and the summary/truncated nature. It could say more about output scale or the need for a live app session, but it is adequate for a simple read-only diagnostic.

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

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

Only one parameter (maxDepth) and schema description coverage is 100%, with a clear default and maximum already documented. The description adds no traversal or truncation semantics beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb+resource (snapshot of the running app's widget tree) and names the source (Flutter Inspector summary tree). An agent can distinguish it from get_selected_widget, though the description does not explicitly contrast with that sibling.

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

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

Gives implied usage contexts ('understand structure, find a widget, or see what is mounted'), which is genuine guidance, but names no alternative and gives no when-not conditions (e.g., when to prefer get_selected_widget or get_rebuilds).

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 carry the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral value by disclosing the verdict enum values (healthy/degraded/failing/no-data), the retention window, and that some numbers carry qualifying notes. It does not describe latency, cost, or staleness, so it stops short of 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 sentences, front-loaded with the one-line value proposition and then the return contents plus the routing directive. Every clause earns its place with no 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?

No output schema exists, so the description must convey the return shape, and it does so well (verdict, five summaries, event ids, retention, qualifiers). With annotations covering safety and a zero-param contract, this is nearly complete; it could note whether data is app-scoped versus session-scoped but that is minor.

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

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

Zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond a no-arg call, though the description could note that no input is required at all.

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 purpose ('is this app healthy right now') and enumerates exactly what it returns (verdict, exception/network/frame/log/memory summaries, retention window, qualifiers). It explicitly distinguishes itself from six sibling get_* tools, so an agent can route without opening any schema.

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

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

Explicitly says 'Call this FIRST instead of calling six get_* tools,' which is a direct when-to-use directive with named alternatives. That is exactly the routing guidance the sibling-heavy list (get_logs, get_exceptions, get_frames, get_network, get_memory, runtime_status) needs.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description still adds substantive behavioral context the annotations lack: event categories, per-category capacity, eviction counts, and the oldest retained event — i.e., that results are bounded by a retention window. No contradictions.

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: the first front-loads the returned content, the second states the use case. Dense but every clause carries information; no filler or restatement of the title. Slightly list-heavy in the first sentence but still efficient.

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

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

There is no output schema, so the description must carry return-value explanation — and it does, detailing connection/session state, per-category event counts, capacity, evictions, and the retention window. Combined with read-only annotations, an agent has enough to call and interpret this correctly; only sibling disambiguation is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to disambiguate and no undocumented inputs to compensate for.

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 ('report connection health, current debugging session, reconnection state, runtime event counts, retention window') and enumerates the reported fields, so an agent knows exactly what comes back. It does not, however, differentiate itself from close siblings like runtime_health or diagnose_runtime, which is the main clarity 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?

It gives a positive use case ('confirm the MCP is receiving live data', 'know how far back the evidence goes'), which is real guidance. But it names no alternative and no exclusion condition, leaving the agent to guess when runtime_status is preferable to runtime_health or diagnose_runtime in the sibling list.

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

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

Annotations already establish read-only, idempotent, non-destructive, closed-world behavior, but the description adds substantive semantics beyond them: network uses interval matching so a request failing inside the window counts even if it started earlier, and baseline directions are reported as unknown rather than fabricated when observation predates the window. These edge-case disclosures are exactly the kind of context annotations cannot carry.

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

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

It is one dense, front-loaded block that leads with what is returned before the mechanics. Every clause contributes information (dimensions, directions, anchoring, interval matching, baseline honesty) with no filler, though the nested parentheticals make it heavier than it needs to be.

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 burden of describing returns falls on the description, and it does so thoroughly: dimensions, direction vocabulary, and citable evidence are all covered, as are anchoring fallbacks and the baseline edge case. Safety behavior is covered by annotations, so the only mild shortfall is the absence of any usage routing against 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?

Schema description coverage is 100%, so both parameters are already well documented, including the eventId default and windowMs bounds. The description largely restates the anchoring default and adds no format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

The description names a specific analytical operation — measuring the incident window against an equal preceding baseline, per dimension, with directions and citable evidence. That baseline-comparison framing distinguishes it from plain sibling readers like get_timeline or get_exceptions, and the listed dimensions make the resource concrete.

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

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

Usage is only implied: it is for reconstructing what preceded a failure, and the anchoring rules (eventId, else most recent exception, else now) are stated. There is no explicit when-to-use/when-not or routing to alternatives such as diagnose_performance or explain_diagnosis, which is a real gap given how many overlapping diagnostic siblings exist.

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