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

Annotations already indicate readOnlyHint=true, and the description adds substantial behavioral detail: it 'compares error rate and p99 latency before vs. after', 'pulls matching ERROR log samples', and 'returns a verdict with a confidence level.' This goes beyond the annotations and helps the agent understand what the tool actually does internally and what kind of output to expect.

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?

Every sentence earns its place: purpose, behavior, and usage guidance are all compressed into three short paragraphs. It is front-loaded with the main purpose and avoids irrelevant details. The structure is clean and 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?

Given an output schema exists (which covers return structure), the description is complete enough. It covers the analysis logic, the window concept, and when to use the tool. The complexity of a multi-step correlation is well summarized, and the agent has enough context to invoke the tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate. It refers to 'the window', which implicitly maps to the lookback_minutes parameter, and the schema shows a required 'service'. However, it does not explicitly explain the parameter names, types, or constraints beyond the vague 'window' mention. The parameter names are self-explanatory but the description adds minimal semantic value.

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

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

The description clearly states the tool's purpose: 'Find whether a recent deploy explains a service's current errors.' The verb 'find' and resource 'recent deploy vs. service errors' are specific. It distinguishes itself from siblings like get_deploys and query_logs by focusing on correlation and before/after arithmetic.

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

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

Explicit when-to-use guidance is provided: 'This is the tool to reach for on "why is X broken"' and it contrasts with the alternative chain of get_deploys + get_metrics + query_logs. This gives the agent clear criteria for selecting this tool over siblings.

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

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

Annotations already declare read-only, and the description adds value by specifying the ordering (newest first) and the behavioral effect of omitting `service` (fleet-wide). It does not describe the time-based filtering or return format, but for a read-only history tool, this is reasonable coverage beyond 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?

Two short, front-loaded sentences: the first states the core purpose and ordering, the second provides a critical parameter hint. Every word earns its place, with no filler or restating 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?

The description covers the core behavior and fleet scoping, and the output schema handles return values. However, it entirely omits the time-filter parameter (`since_minutes`), leaving agents unaware of the default 24-hour window or how to filter by time. Given the tool's simplicity, this gap is noticeable but not fatal.

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 descriptions are 0% for both parameters. The description explains `service` by indicating how to use it for fleet-wide results, but it says nothing about `since_minutes`, which the schema only defines with type and constraints. The name 'since_minutes' is somewhat self-explanatory, but the description fails to compensate for the lack of schema descriptions for all parameters.

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

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

The description clearly states the tool's purpose: retrieving deploy history, ordered newest first. It also distinguishes this tool from siblings by focusing on deploys and mentioning the 'whole fleet' scope, which aligns with the tool's name and differentiates it from services, logs, metrics, and incidents.

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

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

Provides direct guidance on using the `service` parameter: omit it for the whole fleet. This clarifies a key usage decision. However, it does not explicitly mention alternatives or when to use this instead of sibling tools like `correlate_deploy_with_errors`, so it's clear context without exclusions.

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

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

The description reveals that the tool returns min/mean/p95/latest and SLO breach status, adding valuable context beyond the readOnlyHint and openWorldHint annotations. It also conveys the tool's judgment-focused behavior ('so you get the judgement and not just the numbers'), which helps the agent understand the tool's output character. No contradictions 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 description is two sentences, front-loaded with the core purpose. The second sentence adds concise and useful output details without redundancy. Every sentence earns its place, making it highly 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?

Given the tool has 3 parameters and an output schema, the description covers the essential purpose and return value highlights. It doesn't mention edge cases, error scenarios, or relationships to sibling tools, but for a read-only metric summarizer, it is largely complete. Slight gap in usage context prevents 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?

Schema description coverage is 0%, so the description must compensate. It maps the parameters conceptually: 'one metric' → metric, 'one service' → service, 'over a window' → since_minutes. However, it doesn't elaborate on allowed values or the meaning of the metric enum, leaving the schema names to carry the load. This is adequate but not fully compensating for the lack of parameter descriptions.

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

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

The description clearly states the action: 'Summarise one metric for one service over a window.' It distinguishes itself from sibling tools by focusing on metrics and SLO status, but it doesn't explicitly name alternatives like query_logs or correlate_deploy_with_errors, so it misses the top score.

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 through the purpose statement, but the description does not provide explicit guidance on when to choose this tool over its siblings, nor does it mention any exclusions or prerequisites. It merely describes what the tool does, leaving the when-to-use context to the agent.

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

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

Beyond the readOnlyHint annotation, the description discloses that this is the authoritative source for service names and that sibling tools validate against this list. This is useful behavioral context for the agent to plan its workflow.

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

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

The description is concise and front-loaded: the first sentence states exactly what the tool does, and the second sentence adds essential usage guidance. Every sentence earns its place.

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

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

For a simple list tool with no parameters and an output schema present, the description fully covers purpose, usage, and the key constraint of being the discovery entry point. It is contextually 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 has zero parameters, so the description need not explain parameter semantics. The baseline for no parameters is 4, and the description correctly implies no inputs are required.

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

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

The description states a specific verb ('List') and resource ('every monitored service') and clarifies the data returned (team, tier, SLO targets). It is clearly distinct from sibling tools that focus on logs, metrics, deploys, and incidents.

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 explicitly tells the agent to call this tool first when a service name is unknown, and warns that other tools reject names not in this list. This provides clear when-to-use guidance and distinguishes it from alternatives.

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 description goes well beyond the annotations, disclosing that it pages the on-call engineer, requires a non-read-only scope, and rejects read-only callers. This adds important behavioral context about side effects and access control that the annotations alone do not convey.

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 only three sentences, opens with the primary action, and then provides essential usage warnings. Every sentence serves a purpose; no filler or redundant content.

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 action tool with an output schema, the description fully covers the key context: it states the purpose, the real-world side effect, the required scope, and the need for human confirmation. Nothing important 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 input schema has 0% description coverage and the description provides no explanation of the parameters or how to choose severity. The parameter names are somewhat self-explanatory, but the description does not compensate for the lack of schema-level documentation.

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

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

"File an incident" is a specific verb + resource, clearly identifying the action. It stands out unambiguously from the read-only sibling tools like list_services and query_logs.

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

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

The description gives explicit guidance: "use it deliberately" and "Prefer confirming with a human before calling." It also notes the incidents:write scope requirement and that it is the only tool with a real-world side effect, strongly signaling when it should—and should not—be used.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds behavioral context: logs are searched within a time window and returned newest first. It does not contradict annotations and provides concrete ordering/scoping behavior beyond the safe-read label.

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 concise—three short sentences—and front-loaded with the primary purpose. The second sentence offers actionable tips, and the third states ordering. No filler or redundant 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?

Given the output schema exists and annotations cover read-only safety, the description provides sufficient context for a log-search tool. It explains the core use case, useful filtering strategies, and result ordering. The sibling list makes it clear where this tool fits. Missing details like limit defaults are already present in the schema.

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

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

Schema description coverage is 0%, so the description carries the burden. It explains level (filter to ERROR), contains (grep substring), and time window (since_minutes) with concrete examples like trace ID and timeout. It does not explicitly mention limit, but the schema's default/min/max make that self-evident.

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: 'Search a service's logs within a time window.' This clearly distinguishes it from sibling tools like list_services, get_metrics, and get_deploys, which target other resource types. The time-window scope and 'returns newest first' detail further clarify the tool's role.

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 practical guidance: using level="ERROR" to skip noise and contains to grep for substrings like trace IDs or error codes. It implies this tool should be used for log investigation, which contrasts with the metrics/deploy/incident siblings, though it does not explicitly name an alternative or exclusion.

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