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

Annotations already declare readOnly, idempotent, non-destructive operation, so the safety profile is covered. The description adds genuinely new behavioral scope: it analyzes caller-supplied artifacts only and does not query providers, clusters, GitHub, or deploy changes. That closes the open-world question for the caller, though return/report structure is left to 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?

Three sentences, zero waste, front-loaded with the core action and its precondition before the delegation rule and the scope limitation. Each sentence carries distinct 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?

For a high-complexity tool with nested domains and an output schema, the description supplies the mental model (multi-domain correlation, caller-supplied only) and defers return shape to the output schema. Could be marginally better by noting the two-domain minimum applies to required vs optional inputs, but it is largely complete.

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

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

Schema description coverage is 100%, so every nested field (hasWildcardActions, usesPinnedActions, hasPodDisruptionBudget, etc.) is already documented. The description names the evidence domains but adds no format, cardinality, or combination semantics 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 verb (correlate) and resource (evidence from Terraform, IAM, Kubernetes, GitHub Actions into one deployment-risk assessment) plus the secondary output (cross-domain change paths). An agent can tell it apart from the single-domain siblings like review_terraform_security or review_iam_policy 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?

Gives an explicit precondition (at least two evidence domains) and routes the agent to the alternative (domain-specific review tools) when only one domain is available. The when-to-use and when-to-delegate conditions are both spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is covered. The description still adds meaningful nuance beyond them: it analyzes supplied evidence only and never applies a plan, changes infrastructure, or writes Terraform state, which clarifies it is a pure scoring/assessment operation. It does not describe latency or rate-limit behavior, keeping it from a 5.

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

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

Three sentences, zero padding, with the core purpose front-loaded before the sibling routing and the behavioral boundary. Each sentence earns its place.

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

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

For an 8-parameter assessment tool with a full-coverage schema and an output schema, the description need not explain return values. It covers purpose, sibling disambiguation, and the read-only/no-side-effect boundary, which is everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and every parameter is self-documented, so the description owes no parameter detail; baseline 3 applies. It names some evidence categories (rollback, peer review, stateful impact) that map to parameters, but adds no syntax or format meaning beyond what the schema already carries.

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 (Evaluate) plus resource (Terraform/IaC release risk) and enumerates the evidence classes it consumes (plan evidence, rollback, peer review, stateful impact). It explicitly names the sibling review_terraform_security and the boundary between them, so an agent can differentiate without opening 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?

Gives an explicit when-to-use condition ('overall change/release decisions') and a named alternative with its own selecting condition ('for security-only inspection of a raw Terraform plan, use review_terraform_security'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, and the description usefully reinforces and extends this by stating it 'does not execute remediation or make changes to the service' and does not pull live telemetry. That clarifies the generation-only nature of the call beyond the raw safety flags, though it says nothing about cost, latency, or output shape.

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

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

Three tight sentences, no filler, with the core action front-loaded and the exclusions following immediately. Every clause carries distinct 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?

For a generation tool with a full output schema, 100% parameter coverage, and clear annotations, the description supplies everything needed: what it produces, which inputs matter, and what it explicitly will not do. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% with per-field descriptions and two enums, so the schema already carries parameter meaning. The description only echoes the same inputs at a high level and adds no format, constraint, or interaction guidance (e.g. how 'signals' influences triage depth), 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 artifact ('Generate a practical incident-response runbook') and scopes the inputs (service symptom, severity, environment, optional signals). It also rules out adjacent behaviors ('fetch or diagnose from live telemetry', 'execute remediation'), so an agent can tell exactly what class of operation this is even though no sibling generates runbooks.

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

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

Gives explicit when-to-use ('structure response actions and evidence collection') and when-not ('do not use it to fetch or diagnose from live telemetry'), which is more than most definitions. It does not name an alternative sibling tool, so it stops short of a full 5 under the when/when-not/alternatives rubric.

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 structurally. The description adds genuinely useful context beyond them: it is deterministic, makes no external calls, and mutates no service state, which tells the agent the answer is a pure function of the inputs. It does not discuss precision/rounding or failure modes of the calculation.

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, front-loaded with the primary computation, then scope limits, then purity guarantees. No filler and no restatement of the tool name.

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

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

For a pure arithmetic tool with an output schema, complete parameter documentation and full annotation coverage, the description supplies everything an agent needs: what is computed, the optional branch, and the guarantee that nothing external happens.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the relationship the schema only hints at: the request-failure budget is produced only when request counts are supplied, tying requestVolume and failedRequests together as a pair. It adds no units or format detail beyond what the schema already gives.

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 (calculate) and resource (remaining SLO downtime budget / failed-request budget) with the exact condition that activates the second computation. Nothing about it is ambiguous against the review_*/assess_* siblings, which all operate on artifacts rather than performing arithmetic on supplied numbers.

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

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

Explicitly frames the tool as a deterministic calculator and names two things it must NOT be used for (fetching monitoring data, forecasting reliability). That is a clear use/do-not-use boundary, which is exactly what an agent needs to route away from this tool when the user wants live telemetry.

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, destructiveHint=false and idempotentHint=true, so the safety profile is covered; the description reinforces this by enumerating the side effects it will not cause. It also adds a genuine behavioral trait beyond the annotations – that output separates missing evidence from failed controls – but does not cover depth of analysis or evidence requirements.

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 core purpose front-loaded, then routing guidance, then the analysis-only constraint. Every clause earns its place with no restatement of the name or schema.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety and idempotency profile. The description supplies scope, sibling routing, and the no-side-effects guarantee, leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100% across all 8 parameters, including the deploymentStrategy enum, so the schema carries full semantic load. The description adds no parameter-level guidance beyond the structured fields, making the baseline 3 correct here.

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

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

States a specific verb and resource: 'Evaluate generic CI/CD production-readiness controls from structured pipeline facts', and adds the differentiator 'separating missing evidence from failed controls'. It explicitly names the sibling review_github_actions_workflow as the alternative for raw YAML, so an agent can route without opening 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?

Gives an explicit when-to-use ('platform-agnostic delivery process review') and a named alternative with its triggering condition ('for raw GitHub Actions YAML, use review_github_actions_workflow'). It also states the exclusions: analysis-only, no builds, deployments, approvals, or pipeline changes.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile carries less burden on the description. The description still adds valuable context by stating it analyzes supplied JSON only, does not call cloud APIs, and applies deterministic packs. It could say more about output/return behavior, but the added limits are meaningful.

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

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

Three sentences, front-loaded with the core action, followed by routing guidance and a scope/limit statement. Every sentence earns its place with no redundancy.

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

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

An output schema exists, so return values need not be described, and the rich annotations cover the safety profile. Combined with the scope, routing, and no-API-call limits in the description, an agent has everything needed to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema does the heavy lifting. The description nonetheless maps the provider options to concrete policy syntaxes (AWS IAM, Azure RBAC, GCP IAM), reinforcing the provider enum's meaning beyond the schema field name.

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 ('Apply deterministic provider-specific identity policy packs to raw AWS IAM, Azure RBAC or GCP IAM policy documents') and names the sibling it is distinct from. An agent can distinguish this from review_iam_policy without opening 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?

Explicitly states the routing condition: use this for cross-cloud identity analysis, use review_iam_policy for AWS IAM from mixed structured facts or policy JSON. The alternative and its selecting condition are both named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful specifics beyond that: 'examines supplied evidence only and does not call GitHub or dispatch workflows', which concretely reinforces the closed-world, non-mutating behavior. It does not discuss limits or assessment trade-offs, so it stops short of a 5.

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

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

Two sentences, zero filler. The scope is front-loaded in the first sentence and the sibling routing plus closed-world caveat follow immediately after.

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 are rich, so return values and safety need not be explained. The description covers input modes and routing, leaving only minor ambiguity about whether raw YAML and the boolean fact fields can be combined or which takes precedence.

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 is already documented, and the description's facet list largely mirrors the property names rather than adding syntax, precedence, or format detail. Baseline 3 is appropriate when the schema carries the parameter burden; the one mild addition is the implication that YAML input supersedes the boolean fact fields.

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 ('Evaluate') and resource ('GitHub Actions workflow security and deployment readiness') and enumerates the exact facets assessed (triggers, action pinning, token permissions, caching, environment protection, concurrency). It explicitly distinguishes itself from the sibling review_cicd_pipeline, so an agent can route correctly without opening 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?

Names the alternative tool explicitly ('Use review_cicd_pipeline for generic non-GitHub delivery-process review') and describes the input modes it accepts ('structured facts or raw workflow YAML'). The boundary condition for choosing the sibling versus this tool is stated, not inferred.

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 reinforces it with 'does not call AWS or modify IAM', which is useful confirmation of offline analysis. It adds nothing about output shape or limits, but the output schema covers returns.

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

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

Three tight sentences, front-loaded with purpose and risk scope, then routing guidance, then the side-effect boundary. Every sentence carries distinct information with no repetition.

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

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

Given rich annotations, a 100%-covered 9-parameter schema, and an existing output schema, the description supplies exactly what is missing: purpose, sibling routing, and the offline/non-mutating boundary. An agent has everything needed to select and invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by explaining the dual input mode ('structured facts or raw policy JSON') and which risk dimensions each path supports, which helps the agent choose between passing policyJson and the discrete boolean/array fields. It stops short of documenting individual field semantics 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 verb (evaluate/review) and resource (AWS IAM policy), and enumerates what is assessed: wildcard scope, privilege-escalation actions, conditions. It explicitly distinguishes itself from the sibling review_cloud_identity_policy, so an agent can route correctly without opening 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?

Explicit when-to-use (AWS IAM operational risk) and an explicit alternative with its own condition (provider-specific AWS/Azure/GCP policy-pack checks -> review_cloud_identity_policy). It also sets a boundary on inputs ('analyzes supplied policy data only'), leaving nothing to inference.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world behavior, so the bar is lower. The description adds meaningful context beyond them: it operates on 'supplied evidence only and does not connect to a Kubernetes cluster,' which tells the agent not to expect live cluster state. It stops short of describing return shape, though an output schema exists.

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

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

Three sentences, each earning its place: capability and scope first, sibling routing second, evidence-only constraint third. Zero filler and the scope statement 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 12 optional parameters, an output schema and full annotation coverage, the description supplies exactly the missing pieces: what it assesses, how it routes against its security sibling, and that it is offline/evidence-based. Nothing an agent needs to call it correctly is absent.

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% across 12 parameters, so the schema already carries field-level semantics. The description adds framing the schema does not: the two accepted input modes (structured facts or multi-document YAML) and the fact that the checked dimensions map to the boolean flags (probes, resources, replicas, disruption protection, exposure).

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 ('Evaluate') plus resource ('Kubernetes workload') and enumerates the readiness dimensions it covers: probes, resources, replicas, disruption protection and exposure. It also names the sibling it is not (review_kubernetes_security), so an agent can differentiate without opening 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?

Explicit routing: 'Use this for deployability/readiness; for workload security hardening, use review_kubernetes_security.' It gives both the when-to-use and the when-to-use-something-else with the alternative named, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description adds genuine non-redundant context by asserting it 'analyzes supplied YAML only and does not connect to a cluster,' which clarifies that no live cluster state is consulted. It stops short of describing output shape or any limits on manifest size, so not a full 5.

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

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

Three sentences with no filler: scope first, routing second, boundary condition last. Every sentence carries distinct information and the most decision-relevant content 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 present, return values need not be explained, and annotations carry the safety profile. The description supplies the remaining gaps an agent needs: the exact analysis scope, the sibling it competes with, and the fact that it is purely static over supplied YAML.

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 manifestYaml and environment are already documented in the schema, and the environment enum values are self-explanatory. The description adds no syntax, format, or interpretation guidance for either parameter, so the 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?

The description states a specific verb+resource ('Apply Kubernetes workload security rules to manifest YAML') and enumerates the concrete rule categories covered (privileged mode, host access, capabilities, service accounts, seccomp, filesystem, network policy). It explicitly names the sibling review_kubernetes_deployment as the contrasting tool, so an agent can disambiguate without opening 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?

It gives an explicit routing rule: 'Use this for security hardening; use review_kubernetes_deployment for reliability and production-readiness checks.' Both the when-to-use and the alternative with its selection condition are stated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, and the description reinforces this with a concrete operational boundary: 'analyzes supplied artifacts only and does not call registries, CI systems, or clusters.' That closed-world, offline-analysis disclosure is genuinely useful context an agent cannot infer from annotations alone, though it adds little on error behavior or input limits.

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

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

Three front-loaded sentences: the capability, the trigger condition, and the limitation. Every sentence earns its place with no filler or repetition of schema content.

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

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

With an output schema present and 100% schema coverage, the description need not explain return values, and annotations cover the safety profile. It adequately covers scope, trigger, and boundaries; only the absence of named alternatives for narrower sibling tools keeps it from being fully complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by mapping evidence categories onto parameters: action pinning to workflowYaml, image immutability to kubernetesManifestYaml, signing to artifactSigned, provenance to hasProvenance. This explains what role each input plays in the correlation rather than just restating field names.

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 (correlate/assess) and resource (software-supply-chain risk) and enumerates the exact evidence dimensions it fuses: SBOM quality, CI action pinning, Kubernetes image immutability, artifact signing, and build provenance. This distinguishes it from single-domain siblings like review_cicd_pipeline, review_github_actions_workflow, and review_kubernetes_security.

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

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

It gives an explicit precondition ('Use this when an SBOM is available and supply-chain evidence needs to be evaluated together'), which tells the agent this is the cross-domain aggregator. It stops short of naming which sibling tools to prefer for single-domain checks, so it is clear context rather than a full when/when-not routing rule.

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 covered structurally. The description still adds real value by clarifying the operational contract: it 'parses the supplied plan only and does not execute Terraform or write state.' It omits any note on size limits or finding/severity output shape, though the output schema covers returns.

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

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

Three tight sentences: capability first, routing rule second, execution contract third. Every clause carries information and the scoping constraint (parses only) is placed where it matters.

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, complete parameter descriptions, and rich annotations, the description only needs to add scope, sibling routing, and side-effect clarity – all three are present. Nothing an agent needs to select or invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the environment enum's role in contextualizing severity and the plan JSON's expected origin (terraform show -json). The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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

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

Names a specific verb ('Inspect') and resource ('raw Terraform plan JSON') and enumerates the concrete security categories it detects: destructive actions, public exposure, encryption gaps, deletion protection, IAM wildcards. It explicitly distinguishes itself from the closest sibling by naming assess_terraform_change, so an agent can differentiate without opening 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?

States the selection rule directly: 'Use this for Terraform security posture; use assess_terraform_change for broader release/change risk and governance.' This gives both the when-to-use condition and the named alternative with its own condition, leaving nothing to inference.

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