Utility Matrix

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

Annotations already declare the full safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is low. The description usefully adds that it is a deterministic computation and names the three return values, though an output schema already exists, so that disclosure is largely redundant rather than additive.

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 triggering condition followed by inputs and outputs. No filler, no repetition, and the most decision-relevant information leads.

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 deterministic calculator with a complete schema, full annotations, and an output schema, the description covers what an agent needs to invoke it correctly. The only omission is guidance on how it relates to the near-identical on-call-burden-calculator sibling.

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 the schema already documents all four parameters. The description merely restates them (weekly alert volume, actionable %, engineer count, avg resolution time) with no added syntax, units, or edge-case guidance beyond what the schema provides — the expected baseline 3.

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

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

States a specific resource (alert fatigue / noise) and spells out both the inputs consumed and outputs produced (noise rate, wasted hours, fatigue tier). However, it does not differentiate itself from its close sibling on-call-burden-calculator, which is a notable gap given it claims 'on-call burden' as a trigger phrase.

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 opening 'Use when a user asks about alert noise, alert fatigue, or on-call burden from non-actionable alerts' gives clear triggering context. It stops short of naming exclusions or pointing to the overlapping on-call-burden-calculator, which is exactly the kind of disambiguation this sibling set 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a genuine behavioral constraint beyond that: 'satisfied plus tolerating may not exceed total', which tells the agent about an input invariant it must respect.

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 trigger first, then inputs/constraint and output. Nothing is redundant and it is front-loaded with the usage condition.

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, yet the description still summarizes what comes back (score 0–1 plus five-band rating), and the input invariant is covered. Nothing needed 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?

Schema coverage is 100% (baseline 3), and the description goes further by stating the cross-parameter constraint that satisfied + tolerating cannot exceed total, which no single property description in the schema expresses.

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 ('Apdex score calculator') and frames the outcome it produces (user satisfaction with response times). Among the many *-calculator siblings, the Apdex domain is unambiguous, so an agent can route correctly without opening the 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?

Explicit triggering condition: 'Use this when a user asks about their Apdex score or wants to measure user satisfaction with response times.' That is clear context, though it names no alternatives or when-not-to-use conditions.

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

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

The annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds that four time windows are computed, which is mildly useful context, but says nothing about precision, rounding, or edge cases for out-of-range percentages.

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, with the triggering user question front-loaded before the functional summary. Every clause carries information and there is no padding.

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

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

For a one-parameter, pure-computation tool with an output schema and full annotation coverage, the description supplies everything an agent needs to decide to call it and what to pass. Return-value details are correctly delegated to the 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?

With a single parameter and 100% schema description coverage, the schema already documents availability_pct including its format ("e.g. 99.9 for three nines"). The description's "like 99.9% or 99.99%" merely echoes that format, adding no new semantics such as valid bounds.

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 — converting an availability SLA percentage into downtime budgets — with the scope of outputs enumerated (annual, monthly, weekly, daily). This is clearly distinguishable from sibling calculators like error-budget-calculator or slo-burn-rate-calculator, though no sibling is named explicitly.

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

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

"Use this when a user asks what a specific availability percentage (like 99.9% or 99.99%) means in downtime minutes per month or year" gives an explicit, concrete trigger condition. There is no when-not guidance and no named alternative tool for adjacent questions, which keeps it 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 readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is settled. The description adds genuine value by enumerating the detection categories, though it does not say how relative-URL issues are resolved or reported (handled by the output schema).

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 with zero waste; the core action is front-loaded and the detection list follows immediately. Nothing redundant or padded.

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

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

For a read-only, idempotent, closed-world tool with full schema coverage and an output schema, the description covers both inputs and the outputs it produces. 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?

Schema coverage is 100% and both parameters are documented in the schema, including the empty-string convention for a missing canonical. The description adds no syntax or format 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?

States a specific verb+resource ('Audit a page URL against its canonical tag') and enumerates exactly the three conditions detected (missing, self-referencing, relative URL). This clearly distinguishes it from the calculator/linter/scanner siblings, none of which touch SEO canonicalization.

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 description's scope but there is no explicit when-to-use, when-not-to-use, or named alternative. An agent can infer this audits a single page's canonical setup, but nothing routes it against siblings or states preconditions.

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=true, idempotent=true, openWorld=false, destructive=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the exact risk-tiering thresholds (WARNING <30 days, CRITICAL <7, EXPIRED <0), which tell the agent how the tool reasons about its input.

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, with the purpose front-loaded and the return semantics second. Every clause carries information an agent can act on.

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?

A pure two-parameter computation with full schema coverage, safety annotations, and an output schema, so return format needn't be explained. It is essentially complete, with only the missing usage context as a minor gap.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by tying meaning to the days_remaining value through the threshold bands, letting an agent anticipate the outcome for a given input rather than just pass a number through.

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 ('Assess') and resource ('certificate expiry risk') plus the exact inputs it consumes ('domain and days remaining'). It is immediately distinguishable from siblings like known-vulnerability-checker or dockerfile-linter 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?

No when-to-use guidance, no mention of when this is NOT appropriate, and no alternatives named among the large sibling set of calculators. The only hint is the input phrasing 'given a domain and days remaining', which specifies inputs rather than usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds only the output shape (percentage + DORA tier), which is already covered by the output schema — a modest addition, not a rich behavioral disclosure.

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

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

Two short sentences, zero filler, with the invocation trigger front-loaded before the behavioral statement. 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?

With annotations covering safety, a 100%-covered schema for the two params, and an output schema covering returns, the description only needs the trigger and it delivers it. The remaining gap is the lack of routing against the closely overlapping dora-metrics-calculator sibling.

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 documented in the schema. The phrase 'total and failed deployments' names the two inputs in prose but adds no units, units-of-time, or constraint detail beyond the schema — the baseline 3 is correct 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?

The description states a specific verb and resource ('returns failure rate percentage and DORA tier' from deployment counts), and the CFR framing narrows it against generic siblings. It does not explicitly distinguish itself from the overlapping dora-metrics-calculator, 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 when a user asks about change failure rate or DORA CFR' gives a clear, explicit trigger condition. However it names no alternative (e.g., dora-metrics-calculator for the full metric suite) and gives no when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safe/pure-calculator profile is fully covered by structured data. The description adds that it produces a 'waste estimate and tier', but that return detail is also covered by the output schema, so incremental behavioral disclosure is thin. A 3 reflects adequate but minimal added context given the low bar set by 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 sentences, zero waste, with the usage trigger front-loaded before the input/output summary. Nothing superfluous and nothing buried.

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 deterministic calculator with a present output schema and fully described parameters, the description covers when to invoke it, what it consumes, and what it returns. The only gap is that it does not address how the optional inputs (unattached volumes vs. percentages) combine or whether results are exhaustive.

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 the schema already documents all four parameters, and the baseline is 3. The description mentions 'monthly cloud bill and idle/oversized percentages' but omits unattached_volumes_count and adds no syntax, unit, or interaction detail beyond the schema.

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

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

The description names a specific verb+resource ('returns waste estimate and tier' for a cloud-waste calculation) and scopes it with 'cloud waste, idle resources, or unattached storage', which distinguishes it from cost-adjacent siblings such as ec2-cost-calculator and rightsizing-calculator. It stops short of explicitly contrasting those siblings, so it is clear but not maximally differentiated.

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 opening 'Use when a user asks about cloud waste, idle resources, or unattached storage' gives concrete trigger conditions an agent can pattern-match on. It does not name exclusions or point to alternatives (e.g., rightsizing-calculator for pure rightsizing questions), leaving some routing ambiguity among the many cost calculators.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only that the tool is deterministic and reuses the browser calculator's model, which is mild context but not a disclosure the agent couldn't infer.

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

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

Two sentences, zero filler, with the trigger condition front-loaded before the model-fidelity note. Nothing could be removed 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?

With an output schema present, return values need not be explained, and the annotations cover safety. What remains thin is guidance on parameter interaction and defaults, but for a deterministic calculator with fully documented inputs, the description is 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 100%, so the schema already documents all five parameters, and the description merely echoes their names. It adds no units, defaults, or interaction rules (e.g., how system_reserve_pct and target_utilization_pct combine) beyond what the schema states, making the baseline 3 appropriate.

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

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

The description names the specific resource (Kubernetes cluster capacity) and the trigger condition, so an agent can tell this apart from generic siblings like rightsizing-calculator or total-cost-of-ownership-calculator. It never uses an explicit verb like 'calculates', relying on the tool name for that, but the intent is unambiguous.

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

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

'Use this when a user asks for Kubernetes cluster capacity' gives a clear, specific activation context. It stops short of naming alternatives or stating when not to use it (e.g., versus rightsizing or node-count planning tools), so it lands at 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety/determinism profile is fully covered. The description only adds that it shares the browser calculator's model, which is minor extra context; it says nothing about output shape or edge cases, but with annotations carrying the burden a 3 is appropriate.

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 trigger is front-loaded and the model reference follows. No filler, no repetition of the title.

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 and annotations cover the safety profile, so return values and behavioral traits need not be spelled out. The description covers the trigger and inputs adequately; it could note that the output is a recommended pool size, but for a deterministic calculator this is largely sufficient.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the five input names in prose (mapping 'app server count' to app_servers, etc.) but adds no units, ranges, or model semantics beyond what the schema already provides.

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 identifies a specific purpose — calculating how many database connections to configure — and enumerates the input model (max_connections, app servers, DB cores, query duration, peak RPS). It implicitly distinguishes itself from other calculators (cost, SLA, etc.) by naming the connection-pool domain, though it never states the verb 'calculates' explicitly and doesn't contrast with the closest sibling, cluster-capacity-calculator.

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?

States a clear trigger condition ('when a user asks how many database connections to configure'), which is useful routing guidance among 30+ calculator siblings. It offers no exclusions or explicit alternatives, but the trigger is specific enough that an agent can select it confidently.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing behavioral on top — no mention of determinism, required inputs, or what the computed result represents — so it contributes almost no value beyond 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?

It is a single short, front-loaded sentence with zero padding, which is structurally clean. But the brevity comes at the cost of substance — this reads as under-specification rather than disciplined conciseness.

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 and annotations plus 100% schema coverage carry the parameter and safety burden, so the description needn't explain return values. Still, it never states what the calculator produces (e.g., deploys per day per team member), which is the one piece of context the surrounding structured data does not supply.

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

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

Schema coverage is 100%, so all three parameters (deploys_per_month, team_size, working_days) are already documented, and the description adds no additional meaning or interaction notes. Baseline 3 applies 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?

The description names the domain ('deployment frequency', 'DORA deploy cadence') but never states a verb or what the tool actually computes, leaving the action to be inferred from the name alone. It also fails to distinguish itself from the sibling dora-metrics-calculator, which plausibly covers the same DORA cadence territory.

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 single sentence is explicitly a routing trigger ('Use when a user asks about deployment frequency or DORA deploy cadence'), which tells an agent the conversational condition for selecting it. However, it offers no when-not condition and does not address the overlapping dora-metrics-calculator sibling.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds genuinely new behavioral context: findings are returned with redacted matches and a severity classification, which tells the agent how output is shaped and that secrets are not echoed back in the clear.

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 dense sentence, front-loaded with the primary secret-detection purpose before the secondary static-risk enumeration. It is longer than strictly necessary due to the list of risk categories, but each clause maps to a real capability of the tool rather than 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 an output schema present, the description need not detail return values, and it still summarizes them (redacted matches, severity). Input requirements are covered by the schema, and the description supplies enough scope for an agent to call this correctly without opening anything else.

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 'text' parameter is fully documented, including a maxLength and a warning about live production secrets. The description adds no syntax, format, or size guidance beyond what the schema already provides, 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?

The description names a specific verb (scan) and resource (text/config/code/env content), then enumerates both the target artifacts (API keys, tokens, passwords, private keys) and the secondary static-risk checks. This clearly distinguishes it from sibling linters like dockerfile-linter or kubernetes-manifest-linter, which operate on specific manifest formats rather than arbitrary text.

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 parenthetical '(config, code, env files)' implies the intended input contexts, so an agent can infer when the tool applies. However, it never states when to prefer it over adjacent tools such as known-vulnerability-checker, nor does it list any exclusions or prerequisites. Usage is implied rather than directed.

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 closed-world, so the safety profile is covered. The description adds substantive behavioral context beyond that: the specific rule set enforced, the backslash line-continuation parsing rule, and the fact that each issue is reported against its original line number.

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 action and scope before drilling into the rule list, and the second sentence covers parsing/reporting semantics. The dense rule enumeration is long but each item earns its place by telling the agent what will be flagged.

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 needn't be detailed, yet the description still notes that issues carry original-file line numbers. Combined with annotations covering safety and a fully documented single parameter, the definition is complete for correct invocation; only the sibling-boundary guidance 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% and the single parameter is documented as 'Dockerfile content (full or partial), up to 8,192 characters.' The description adds meaning the schema does not, clarifying that multi-line joined instructions count as one and that issues map back to original file lines. Baseline would be 3 at full coverage; the added parsing semantics lift 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?

States a specific verb (lint), a specific resource (a Dockerfile), and the exact scope (a rule-based subset of Hadolint checks), then enumerates the rules checked. The Dockerfile resource inherently distinguishes it from the nearest sibling, kubernetes-manifest-linter, without the agent needing to open either 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?

The purpose strongly implies when to reach for it (a Dockerfile you want checked), so usage is implied rather than stated. There is no explicit when-not guidance and no naming of adjacent siblings like kubernetes-manifest-linter or detect-secrets-scanner, so an agent must infer the boundary itself.

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 real behavioral value beyond that: fixed elite/high/medium/low benchmark bands, an omitted restore time surfacing as 'unknown', and the overall profile being marked 'partial rather than assumed' — a non-obvious handling of missing input.

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, usage condition front-loaded, zero filler. The dense second sentence carries classification semantics and missing-input handling, all of which earn their 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 shape need not be described, and annotations cover the safety profile. The description supplies the missing conceptual layer — benchmark bands and partial-profile behavior — making the tool callable without ambiguity; only the sibling-routing gap keeps 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?

Schema description coverage is 100%, so all four parameters including units and the optional/unknown behavior of restore_time are already documented in the schema. The description restates the units and list of inputs but adds no syntax or format detail beyond the structured data. Baseline 3 applies.

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

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

States a specific verb and resource ('benchmark an engineering team against DORA metrics') and enumerates the four inputs it consumes. However, it never distinguishes itself from the many near-overlapping siblings such as deployment-frequency-calculator, change-failure-rate-calculator and mttr-calculator, so an agent must infer that this is the composite/all-four-metrics tool rather than the single-metric ones.

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

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

'Use this when a user wants to benchmark an engineering team against DORA metrics' gives a clear triggering context, but there are no exclusions and no alternatives named. Given that siblings cover each DORA metric individually, an explicit 'for a single metric use X instead' would materially help routing.

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 useful context that it returns a DO-equivalent savings estimate, a behavior not evident from the name. It doesn't add constraints, defaults, or rate-limit 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 tight sentences with the trigger front-loaded ahead of the return description; every clause earns its place. Minor imprecision: it implies hours is needed, yet only instance_type is required.

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 needn't be re-explained, and annotations carry safety. Remaining gaps are the optional status/default of hours_per_month and os, plus no sibling routing among numerous cost calculators.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, establishing the baseline of 3. The description mentions only instance type and hours, omitting os, and adds no format or default details 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 verb+resource: returns monthly cost and a DO-equivalent savings estimate for EC2. It is clearly about EC2, which separates it from the many sibling cost calculators (egress, pipeline, query). However, it does not explicitly name or contrast against those siblings.

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 when a user asks about EC2 cost" gives a clear trigger condition. But there is no when-not guidance and no routing to alternatives such as rightsizing-calculator or reserved-instance-breakeven, leaving the agent to infer boundaries among many overlapping cost 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile requires no description support. The description contributes one genuine behavioral claim - parity with the browser calculator's model - which is useful for trusting the output, but says nothing about pricing basis, rounding, or currency.

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, with the usage trigger front-loaded and the model-provenance note trailing. Every clause carries information the agent can act on.

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 no explanation, and annotations cover the safety profile. Inputs are all enumerated and the deterministic nature is implied, but the description never states the pricing basis (published on-demand list prices) or what happens to provider/cdn_pct when omitted, which are minor but real gaps for a cost-figure tool.

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

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

Schema description coverage is 100% and provider is an enum, so every parameter is already documented in the schema. The description merely restates the four inputs (daily request volume, average response size, provider, CDN offload) in prose, adding no format, unit, or default information beyond the schema. Baseline 3 is appropriate.

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

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

States a specific computation (monthly internet egress cost) plus the exact inputs that drive it, which cleanly separates it from cost siblings like ec2-cost-calculator or pipeline-cost-estimator. It stops short of naming any sibling it is not, so differentiation is inferred from the narrow domain rather than stated.

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

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

The opening 'Use this when a user asks about...' is a concrete positive trigger, which is better than nothing. However there is no when-not guidance and no routing to alternatives such as ec2-cost-calculator for compute spend or cloud-waste-calculator, so the agent must infer the boundary itself.

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, non-destructive and closed-world, so the safety profile is covered. The description adds the output shape and the status classification (Under budget / Elevated / ALERTING), which is useful context, but since an output schema exists this is largely duplicated rather than new behavioral disclosure.

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

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

Two sentences, zero waste: the trigger condition is front-loaded and the return contract follows. Nothing padded or duplicated for its own sake.

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 a full output schema present, the description need not explain return values, and it covers triggers adequately for a read-only calculator. The one meaningful gap is routing against slo-burn-rate-calculator, whose scope overlaps almost entirely with the 'burn rate' trigger phrase used here.

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%, with each of the four parameters documented in the schema itself, so the baseline is 3. The description mentions only 'SLO percentage and window' and adds no format, unit, or default detail beyond what the schema already states.

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 computation (error budget from SLO percentage and window) and names the outputs, so the purpose is clear. It does not, however, distinguish itself from the closely named sibling slo-burn-rate-calculator, which the description only incidentally touches by mentioning 'burn rate multiplier' as an output.

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 opening sentence gives explicit trigger conditions ('when a user asks about their SLO error budget, remaining error budget, or burn rate'), which is strong context. It stops short of excluding the obvious alternative (slo-burn-rate-calculator), so an agent must still infer which of the two to pick.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, fully covering the safety profile of a pure computation. The description restates the input/output composition but adds no behavioral context beyond what annotations and the output schema already convey, so a baseline 3 is appropriate.

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 with a front-loaded use case, followed by inputs and outputs. Every sentence earns its place with 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?

For a deterministic calculator with full annotation coverage and an output schema, the description gives an agent enough to call it correctly. It does omit mention of two optional inputs (eng_hourly, responders), which the schema covers, so it is complete but not maximally so.

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 the schema already documents all five parameters. The description mentions hourly revenue, downtime duration, and affected percentage, which maps to three of them but omits eng_hourly and responders and adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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 gives a specific verb+resource: calculating the financial impact of an outage/incident, naming concrete outputs (revenue impact, engineering cost, total). This is clearly distinct from every sibling (mttr-calculator, dora-metrics-calculator, ec2-cost-calculator, etc.), but it never explicitly contrasts itself with a nearest alternative, so it lands at a strong 4.

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 a clear triggering condition: 'Use this when a user asks what an outage or incident cost, or wants to calculate the financial impact of downtime.' That is an explicit when-to-use context, though it offers no when-not-to-use guidance or named 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, and the description goes further by disclosing the core limitations: no live feed querying, no version-range assessment, and no guarantee of vulnerability or safety. That is exactly the kind of caveat an agent needs to avoid misreporting 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?

Two tight sentences with no filler; the scope statement leads and the critical limitations follow immediately. Every clause carries information the agent needs.

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 unnecessary. For a one-parameter lookup whose main risk is being mistaken for live vulnerability intelligence, the description covers purpose, scope limits, and non-guarantees adequately.

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% with a single parameter, so the schema already documents accepted forms (lodash@4.17.21, log4j-core, @babel/core) and the non-assessment of versions. The description adds no parameter detail beyond what the schema supplies, 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 first sentence states the resource and mechanism ('historical curated package-name advisory reference'), and the second clarifies the operation ('matches older CVE examples for common packages'). It is clear what the tool does, though the framing is more noun-phrase scope statement than a crisp verb+resource, and no sibling is named (though no sibling here is a genuine alternative).

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?

Strong when-not guidance: it explicitly says it does not query live feeds or evaluate installed version ranges, which steers the agent away from treating it as a real vulnerability oracle. It does not name an alternative tool for live advisory data, so it falls short of a full 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 readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds that it returns an issue list with severity, which is useful, but says nothing about malformed YAML handling, whether the check set is exhaustive, or whether findings are blocking — so this is only modest added value beyond the 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 sentences, no filler, with the purpose front-loaded and the detected issue classes listed compactly. Every clause earns its place by telling the agent what the lint covers.

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

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

With an output schema present and annotations covering safety, the description need not explain return values, and the single parameter is fully documented in the schema. It is nearly complete for a deterministic read-only linter, with only minor gaps around invalid-input behavior.

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 a single parameter with 100% schema description coverage ('Kubernetes manifest YAML content'), so the schema already carries the semantics. The description confirms the input is YAML but adds no syntax, encoding, or multi-document guidance beyond what the schema states, which is the baseline 3 for a fully documented single-parameter tool.

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 gives a specific verb (Lint) and resource (Kubernetes manifest YAML) and enumerates the exact classes of issues detected (resource limits, health checks, :latest tags, privileged containers), which makes the tool's scope concrete. It separates itself implicitly from dockerfile-linter by naming the artifact type, but never explicitly differentiates from that sibling or states scope limits (e.g., only these four checks).

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

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

There is no explicit when-to-use or when-not-to-use guidance and no naming of alternatives such as dockerfile-linter or detect-secrets-scanner. The enumerated checks imply the domain but leave the agent to infer when this tool is the right call versus a neighboring linter.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the accepted input shape but says nothing about aggregation across multiple incidents, the recovery-time formula, or error behavior on malformed timestamps.

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 usage trigger and followed by the input contract; nothing is wasted. The second sentence is dense but compact, 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?

An output schema exists, so return values need not be explained, and the single required parameter is described. The remaining gap is disambiguation from dora-metrics-calculator and clarification of how the three timestamps map to the reported MTTR, which matters for a metric calculator in this crowded sibling set.

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%, but the schema's own parameter text ("incidents used by this deterministic tool.") is uninformative, so the description's specification of the two accepted formats — comma-separated "start,detected,resolved" lines or an array of objects — is genuinely additive. It still leaves the meaning of "detected" versus "start" for the MTTR computation ambiguous.

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

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

The description names the metric (MTTR / DORA recovery time) and the input it operates on (incident timestamps), so the verb+resource is identifiable. It does not, however, distinguish itself from the sibling dora-metrics-calculator, which plausibly overlaps on the same metric family.

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 when a user asks about MTTR or DORA recovery time" gives a clear triggering condition for selection. It stops short of any when-not guidance or explicit routing to alternatives such as dora-metrics-calculator for the full DORA suite.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and determinism profile is largely covered. The description adds that it is deterministic and mirrors 'the browser calculator exactly,' a modest but real addition about result parity; it says nothing about units of the output or precision beyond what the schema carries.

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, with the usage trigger front-loaded before the input summary. Appropriately sized for a simple deterministic calculator.

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 and annotations carry the safety/determinism profile, so the description need not explain return values. For a low-complexity, three-required-parameter calculator, the entry is sufficient, though the vague 'burnout risk' framing is never grounded in what the computed number actually represents.

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

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

Schema description coverage is 100%, so all three parameters are documented structurally, and the description merely names the same inputs (team size, rotation length, hourly rate). It adds no syntax, formatting, or edge-case guidance beyond the schema's minimum/exclusiveMinimum constraints.

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 and title together convey that the tool computes an on-call burden figure from team size, rotation length, and hourly rate. The purpose is clear, but it never explicitly distinguishes itself from the closely related alert-fatigue-calculator or burnout-adjacent siblings, so the agent must infer the boundary.

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 when a user asks about on-call load or burnout risk" gives a clear triggering condition. It lacks any exclusion or alternative guidance, which matters given 30+ sibling calculators including alert-fatigue-calculator that could plausibly be confused with this one.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive domain behavior: GitHub list prices effective 1 Jan 2026, GitHub Free's 2,000 included minutes for private repos drawn at list price, and zero GitHub charge for self-hosted. It does not discuss output shape, but an output schema exists so that burden is lifted.

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?

Four sentences, front-loaded with the usage trigger, then inputs, then pricing assumptions and billing caveats. Every sentence carries information and nothing is repeated for 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 pure computational tool with a complete input schema and an output schema, the description supplies exactly the extra context an agent needs to trust the result: pricing basis, effective date, free-tier treatment, and self-hosted semantics.

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 the schema already documents all four parameters, including the runner labels, case-insensitive matching, and the Linux default. The description mostly restates these (runner labels, case-insensitivity) and adds only the cost-relevant note that self-hosted minutes are free, so it hovers at the baseline.

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

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

States a specific verb (calculates cost) and resource (GitHub Actions CI/CD pipeline cost per month), which cleanly separates it from siblings like ec2-cost-calculator, egress-cost-calculator, and cloud-waste-calculator. An agent can identify the tool's domain without opening the 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?

The opening sentence gives an explicit trigger: 'Use this when a user asks how much their GitHub Actions CI/CD pipeline costs per month.' It is a clear context for use, but it names no alternative cost tools and gives no when-not-to-use condition for overlapping sibling calculators.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only that beta is optional and that the output includes a tradeoff interpretation; it doesn't address edge cases such as both inputs being zero.

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: trigger first, then inputs and outputs. No filler, no repetition of the title, and the most decision-relevant information is front-loaded.

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

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

With an output schema handling return values and annotations handling safety, the description only needs to orient the caller, which it does. Minor gap: no note on degenerate inputs (precision=recall=0) or that the result is a pure deterministic computation, though the schema hints at determinism.

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 the 0-1 bounds, required status of precision/recall, and the beta parameter are all documented structurally. The description restates the fraction range and beta optionality without adding format or semantic detail beyond the schema baseline.

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

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

The description states a specific computation (F1/F-beta from precision and recall) and names its inputs and outputs. In a sibling set of cost/SLO/DevOps calculators, an ML-metric tool is unmistakable, so no differentiation problem exists.

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 opening sentence gives an explicit trigger: use it when a user asks about ML model precision, recall, F1, or F-beta. It stops short of stating when NOT to use it or naming an alternative, but no sibling overlaps with this domain, so the omission is low-cost.

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, openWorldHint=false, and destructiveHint=false, so the safe deterministic profile is covered. The description adds that this is a pure estimate using a known four-input model, consistent with the annotations, but adds no extra behavioral context beyond that.

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 operation and its inputs, with no padding. The trailing sentence about the browser calculator is mildly useful context rather than filler.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. For a deterministic estimator with fully documented parameters, the description is complete enough, though a note on the underlying cost model would add value.

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

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

Schema description coverage is 100%, so all four parameters (table_rows, table_pages, selectivity_pct, storage_type) are already documented, including the storage_type enum. The description only restates the input list without adding syntax or modeling detail, so the baseline 3 applies.

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

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

States a specific verb (Estimate) and a precise resource (PostgreSQL sequential-scan and index-scan cost), then names the four inputs. It is clearly distinguishable from sibling cost calculators (ec2-cost-calculator, terraform-plan-cost-estimator) though it does not explicitly contrast itself with them.

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-tool guidance. The reference to 'the same four-input model as the browser calculator' gives context about consistency but tells the agent nothing about when this tool is the right pick.

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 this is a safe, read-only, idempotent computation. The description adds genuinely useful behavior beyond that: the risk-band thresholds (OK <80%, WARNING 80-95%, CRITICAL >95%) and the shape of the result (percentage, buffer, safety status, risk level).

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 tightly written sentences: the computation first, then the output and thresholds. No filler, no repetition of the title.

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?

A simple, fully documented calculator with 100% schema coverage and an output schema, so return values need not be explained. Everything an agent needs to invoke it is present.

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 schema already documents current_requests, limit, and window_seconds. The description restates two of the three parameters but adds no format or semantics 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?

States a specific verb and resource ('Calculate API rate limit utilization') and names the inputs it operates on. Among a large family of calculator siblings, this one's domain is unambiguous.

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

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

The purpose implies when it is useful (checking headroom against a limit), but there is no explicit guidance on when to reach for this versus related calculators like slo-burn-rate-calculator or error-budget-calculator, and no stated exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them by disclosing the decision logic: terms are judged independently, a recommendation is made only when a term saves money over its own length, and 3-year is preferred only when it beats three consecutive 1-year terms. That is exactly the kind of hidden reasoning an agent needs to interpret or trust the result.

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?

Four dense sentences, no filler: trigger first, inputs second, output third, recommendation policy last. Every sentence carries distinct information and the ordering matches how an agent would use it.

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

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

With an output schema present and annotations covering safety, the description supplies the remaining missing layer — the recommendation rules and separate per-term evaluation — so an agent knows not just how to call it but how to interpret and relay the result.

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

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

Schema description coverage is 100% and the description mostly restates schema facts ('optional upfront fees (0 when omitted)'). It adds no syntax or semantics beyond what the parameter descriptions already say, so the baseline 3 applies.

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

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

Names a specific verb+resource (break-even calculation between Reserved Instances and On-Demand) and states the exact scope: judging 1-year and 3-year terms separately and returning each break-even month and net saving. No sibling in the list (ec2-cost-calculator, cloud-waste-calculator, total-cost-of-ownership-calculator) overlaps this specific decision, so an agent can route here without opening schemas.

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

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

Front-loads an explicit trigger: 'Use this when a user asks whether to buy Reserved Instances or stay on On-Demand, or how long an RI takes to pay for itself.' That is clear when-to-use context, though it names no exclusions or alternative tools (e.g., when to prefer the general cost calculators instead).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds nothing behavioral beyond that — no note that the calculation is deterministic, no required-input prerequisites, no unit or cost caveats. With the low bar set by annotations it still fails to contribute any additional 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?

A single sentence with no filler and the trigger front-loaded, so there is no waste. However, at this length the brevity reads as under-specification rather than tightness — the one sentence does not carry the load a 6-parameter calculator requires.

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 deterministic 4-required-parameter calculator the description omits what inputs are mandatory in practice, what units/assumptions drive the result, and how it differs from cost-oriented siblings. Adequate to recognize the tool, thin for calling it correctly with confidence.

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% across all six parameters, so the baseline is 3. The description mentions no parameter at all — not the required p99 inputs, not the units of hourly_cost, not instance_count — so it adds no meaning beyond the schema. Note the schema text itself is largely templated ('used by this deterministic tool'), but the description does nothing to compensate.

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 identifies the domain ('instance rightsizing', 'overprovisioned compute') but never states what the tool actually does — compute recommended vCPU/memory from p99 utilization inputs — or what it returns. It is framed entirely as a usage trigger rather than a verb+resource statement. It loosely separates from siblings like ec2-cost-calculator, but not from cloud-waste-calculator, which plausibly covers the same overprovisioning territory.

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 concrete trigger condition ('when a user asks about instance rightsizing or overprovisioned compute'), which is exactly the context an agent needs to route here. It stops short of naming when NOT to use it or pointing to overlapping siblings such as cloud-waste-calculator or cluster-capacity-calculator, so it is 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the agent knows this is a pure, side-effect-free computation. The description adds that it returns burn rate and hourly budget consumption, but that is already implied by the output schema and the name, so added behavioral context is thin.

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 trigger condition and followed by the computation. The closing sentence about returns largely duplicates the output schema, so it is slightly padded but still tight overall.

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 full schema coverage, an existing output schema, and read-only annotations, the description covers everything needed to invoke the tool correctly. The one remaining gap is sibling differentiation (error-budget-calculator, availability-sla-calculator) in a large family of similar calculators.

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

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

Schema description coverage is 100%, so every parameter (errors, total, slo, window_hours) is already documented in the schema. The description restates the input set without adding units, format, or constraints beyond 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 computation (burn rate and error-budget consumption per hour) from named inputs, so the purpose is unambiguous. It does not, however, distinguish itself from the closely-related sibling error-budget-calculator, 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 explicit trigger conditions in user-intent terms: 'when a user asks how fast they are burning their error budget, or whether their current error rate will exhaust their SLO window.' That is a clear when-to-use, but no when-not-to-use and no routing to the sibling error-budget-calculator.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing on top of that: no mention that the computation is deterministic, no note on how the 1-5 risk scales behave, no statement about what a caller gets back. With annotations carrying the safety load, this remains a gap rather than a strength.

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

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

It is a single, front-loaded sentence with no filler, which is structurally clean. But for an 8-parameter tool the brevity edges into under-specification rather than disciplined conciseness.

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. Still, the tool takes 8 inputs including bounded ordinal scales (changeManagementRisk and vendorStabilityScore, both 1-5) whose directionality and meaning are undocumented anywhere, and the description does nothing to resolve that. For a multi-input scoring model this is incomplete.

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 nominally 100%, which sets the baseline at 3, but every parameter description is the same boilerplate ('X used by this deterministic tool') and conveys no domain meaning. The description itself supplies zero parameter guidance, so it neither compensates for nor improves 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 only supplies a trigger phrase ('Use when a user asks about risk of a software purchase or SaaS commitment') and never states what the tool actually computes or returns. It essentially restates the name/title 'Software Purchase Risk Calculator' in different words rather than adding a distinct verb+resource statement. An agent learns nothing beyond the already-visible tool name.

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 single sentence is a usage condition, so a trigger is provided ('risk of a software purchase or SaaS commitment'). However, there is no when-not guidance and no differentiation from the 31 siblings, several of which overlap heavily (total-cost-of-ownership-calculator, cloud-waste-calculator, reserved-instance-breakeven).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds no behavioral context beyond the usage trigger, such as determinism, limitations, or scope restrictions.

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

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

The description is a single front-loaded sentence with no wasted words. It is appropriately sized for the amount of information it conveys.

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 schema and output schema are rich, and annotations cover safety traits, so the description need not explain return values. However, it does not clarify how a Terraform plan maps to the required resource_type, count, and instance_size inputs, nor does it differentiate from numerous sibling cost calculators.

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 the schema already documents all three parameters. The description does not add any parameter-level meaning, making the baseline score of 3 appropriate.

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

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

The description states a specific action and target: estimating monthly cost of a Terraform plan. It is clear what the tool does, though it does not explicitly differentiate itself from closely related cost estimators beyond the Terraform plan wording.

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 trigger: use when a user asks to estimate monthly cost of a Terraform plan. It does not provide when-not-to-use guidance or name alternative sibling tools, but the intended context is explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the full safety profile of this side-effect-free computation is covered by structured data. The description adds no behavioral context of its own (no mention of determinism, formula scope, or units), but for a pure read-only calculator with complete annotations there is little left to disclose. 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?

A single front-loaded sentence with zero filler; the trigger is stated immediately. It is efficient but so terse that the brevity tips into under-specification rather than genuine conciseness, which caps it below 5.

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

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

An output schema exists, so return values need not be explained, and rich annotations cover the safety profile of this read-only computation. The remaining gap is param semantics and sibling routing for an 8-parameter financial model, which the one-line description does not address.

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 nominally 100%, so the baseline is 3 per the rubric. The description contributes nothing about any of the 8 parameters, and the schema descriptions are generic placeholders, so no extra meaning is added. Baseline 3 is the correct landing spot.

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

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

The description names the domain (TCO, multi-year SaaS cost) and the name itself signals a calculator, so an agent can infer the resource being computed. However, it never states what the tool actually computes or returns, reading as a trigger phrase rather than a purpose statement. It only partially separates this tool from the many other cost siblings (ec2-cost-calculator, pipeline-cost-calculator, software-purchase-risk-calculator).

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 when a user asks about TCO or multi-year SaaS cost" gives an explicit trigger condition, which is real usage guidance. It offers no when-not, no prerequisites, and no routing against the crowded set of cost-oriented siblings, so an agent facing an ambiguous cost question still has to guess. This is implied-to-partial guidance rather than a complete selection rule.

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