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

With no annotations, the description carries the full disclosure burden and does it well: it names the underlying mechanism (`composer audit`), the failure modes (no composer.lock, composer not found), and, critically, that it returns scanned=false with a reason rather than reporting a false zero. That failure-semantics detail is exactly the kind of behavior an agent cannot infer from the 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, both load-bearing: the first establishes scope, the second establishes failure semantics. It is slightly dense with an em-dash appositive list, but nothing is redundant and the scope statement 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?

An output schema exists, so return-value explanation is not required, yet the description still adds the one return contract that matters (scanned=false on a skipped check). With one simple required parameter and the mechanism, scope, and failure behavior all stated, nothing an agent needs to 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% on a single parameter, so the schema already documents that `path` is the project root holding composer.json. The description only restates the same relationship ('the given Magento project') without adding format or edge-case detail beyond the schema. 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?

Specific verb (checks against known security advisories) and precise resource scope (every installed package in composer.lock: core, vendor, dev dependencies). The explicit contrast 'not just custom app/code' distinguishes it from narrower siblings like scan_module_risk without naming 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?

The stated scope makes the intended context clear — you run this to audit dependency advisories rather than custom code — which implicitly separates it from scan_module_risk and check_outdated_packages. However, no alternative tool is named and there is no explicit 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?

With no annotations, the description carries the full burden and does well: it discloses exact scope (only check_updates per project, plus code_compatibility when rector.php exists), the reasoning for omitting expensive checks, and batch failure semantics (a bad path errors individually instead of failing the whole call). It stops short of stating whether the operation is read-only or how long a fleet-wide run may take, so it is strong but not exhaustive.

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 purpose and dense with distinct facts (scope, cost rationale, caveat, error handling); no filler sentences. It is on the long side with nested clauses, but each sentence delivers a separate, actionable point.

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

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

Given an output schema exists (so return values need not be described) and the batch/nested-parameter complexity is low, the description covers everything an agent needs: what it runs, what it deliberately omits, the important false-negative caveat about blocked=false, and per-project error containment.

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% for all three required params, so the baseline is 3. The description reinforces the aggregate semantics of 'paths' (one per project) and the target versions, but adds no syntax, format, or edge-case detail beyond what the schema already documents.

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 (triages) and resource (many Magento projects/fleet) and even frames the question it answers: 'which of these N stores can be upgraded today'. It explicitly contrasts itself with build_upgrade_plan and the heavier scan_module_risk/audit_security siblings, so an agent can distinguish it 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 explicit when-to-use ('triages many projects at once', 'today' triage) and when-not-to-expect-completeness, plus a prescribed follow-up ('call build_upgrade_plan per project afterward for the full picture'). The alternative path is named rather than left for 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?

With no annotations, the description carries the full behavioral burden and does substantial work: it defines what qualifies as a blocker, declares check_outdated_packages and vendor/-scope scan_module_risk findings as informational-only, and warns that ready=true ignores the 'unverified' list. It does not state whether the tool mutates anything or any runtime/performance expectations for running five sub-checks, leaving modest gaps.

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

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

Purpose and the composed tool list are front-loaded, and the sentences are dense with decision-relevant content rather than filler. It is on the long side and re-explains return-value semantics the output schema likely already covers, which costs a point.

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 multi-tool orchestrator this covers the essential surface: inputs, what is combined, blocker vs informational semantics, and the ready/unverified caveat. Since an output schema exists, the description needn't detail return shape, and the remaining omission (side-effect/performance profile against a local filesystem path) is minor.

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

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

Schema description coverage is 100% for all three required parameters, so the schema already documents path, target_php and target_magento with format examples. The description adds no parameter-level detail beyond what the schema provides, 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 ("Builds an upgrade plan") and immediately scopes it to a Magento project against target PHP/Magento versions. It also names the exact siblings it composes (check_updates, scan_module_risk, audit_security, check_outdated_packages, fetch_release_notes), which cleanly distinguishes this aggregator from the individual check tools.

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 composition list makes clear that this is the orchestration entry point rather than a call to each sibling individually, and it explains how to interpret output signals that select routes (blockers vs informational). It does not, however, explicitly state when NOT to use it (e.g. when you only need one check), so guidance is strong but not exhaustive.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses the data source (composer.lock vs `composer outdated`), the per-package latest-status values (semver-safe-update vs update-possible), and a failure mode where scanned=false plus a reason is returned instead of a misleading zero. It stops short of stating permissions, runtime cost, or whether the scan hits the network.

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 core action is front-loaded in the first clause, and the differentiation and failure-mode notes are dense rather than padded. The single long em-dash-heavy sentence runs on, but no sentence is wasted.

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

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

An output schema exists, so return-value documentation is not required, yet the description still explains the per-package status field and the scanned=false degradation path. For a one-parameter scan tool this covers everything an agent needs to call it and interpret 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 single `path` parameter is fully documented in the schema as the project root holding composer.json. The description adds only the related detail that composer.lock lives there, which does not extend meaning beyond the schema. 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 ('Checks every installed package ... against `composer outdated`') and anchors it to a concrete artifact (composer.lock in the Magento project root). It explicitly separates itself from two named siblings, audit_security and check_updates, so an agent can pick it 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?

Names both alternatives and the precise condition that selects this tool: a package can be behind on releases with neither a CVE nor a compatibility issue, 'and that's still tech debt worth surfacing.' That is an explicit when-to-use rationale plus implicit when-not (use audit_security/check_updates for those concerns).

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

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

With no annotations, the description carries the full disclosure burden and does substantial work: it explains that declared requirements are often '*' and can give a false sense of readiness, that code_compatibility requires a Rector dry-run, and that the PHP source is resolved from cache, live fetch, or offline fallback table in that order with the result disclosing which. Auth, rate limits, and likely runtime cost of the dry-run are still unstated.

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

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

Purpose is front-loaded in the first clause, and the two signals plus the fallback chain follow in a logical order. It is dense and sentence-heavy, with the parenthetical about '*' being essentially a second clause inside an already long sentence, but almost every statement carries real information.

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

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

An output schema exists, so return values need not be described, and the description still explains the shape of the two results and the provenance of the PHP requirement. For a moderately complex, multi-signal check with no annotations, the remaining gap is operational (expected runtime, whether it mutates the working tree via the dry-run) rather than conceptual.

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 (path, target_php, target_magento) are already documented with examples ('8.3', '2.4.7') in the schema. The description reinforces what the inputs mean but adds no format or constraint detail beyond what the schema already provides, 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 verb and resource: it checks a Magento project's readiness against a target PHP and Magento version, and it enumerates the two signals produced (per-package verdict and code_compatibility). That is far more precise than the bare name, but it never positions itself against close siblings like outdated_packages or upgrade_plan, so an agent must infer the distinction.

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

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

Usage is only implied: an agent can infer this is an upgrade-readiness check to run before/alongside upgrade_plan, but the description names no alternative, no when-not-to-use condition, and no prerequisites beyond needing a project root with composer.json. It contextualizes the result rather than the invocation decision.

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

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

With no annotations, the description carries the full burden and does disclose meaningful behavior: the authoritative data source, an explicit anti-hallucination guarantee ('never reconstructs them from training data'), and the failure contract ('returns found=false with a reason ... rather than guessing'). It does not cover auth requirements, rate limits, or network/error conditions beyond the not-found case, so it falls short of a 5.

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

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

Two sentences, front-loaded with the action and source, followed by the failure-mode contract. No filler or redundant restatement of the tool name; every clause adds information.

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

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

An output schema exists, so return-value shape needn't be explained, and the description still covers the source of truth and the found=false outcome. What remains thin is operational context (auth, rate limits, offline behavior), which matters for a GitHub-API-backed tool but is unmentioned.

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 there is a single parameter whose schema already documents the expected format ('2.4.7'). The description adds no format, normalization, or range guidance beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb+resource ('Fetches Magento's own release notes') and names the exact source (magento/magento2 GitHub repo's Releases API), so the agent knows precisely what it gets and from where. It is clearly distinguishable from sibling tools like security_audit, check_updates, and upgrade_plan, which operate on installed projects rather than fetching upstream notes.

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

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

The description implies usage (you supply a version and get that version's upstream notes), and the 'never reconstructs from training data' phrasing hints it should be preferred over inferring notes. However, it never explicitly says when to choose this over check_updates or upgrade_plan, nor are any prerequisites stated. Usage is implied rather than instructed.

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

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

No annotations are provided, so the description carries the burden; it discloses that the operation only reads composer.json/composer.lock and adds a useful performance trait (fast, composer-only vs slower deeper checks). It does not explicitly state there are no side effects or what happens on a missing/invalid path, so it stops short of full 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, and the output summary is front-loaded before the routing advice. Every clause earns its place by either describing the return or directing sequencing.

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 the description needn't explain return values, and it already covers the read source and its place in the tool sequence. The only residual gap is unspecified error behavior for a bad path, which is minor for a single-parameter read tool.

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

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

There is one parameter with 100% schema description coverage, so the schema already defines 'path' as the project root holding composer.json. The description's phrase 'given Magento project' 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 and resource ('Reads composer.json and composer.lock of the given Magento project') and enumerates the returned state: Magento version, PHP requirement, package count, abandoned packages. This clearly separates it from siblings like check_updates or scan_module_risk.

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

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

Explicitly says 'Call this first' for a fast overview before 'the deeper (and slower) checks like check_updates, scan_module_risk or build_upgrade_plan'. Names both the trigger condition and the alternative tools, 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?

With no annotations, the description carries the full burden and does so richly: it discloses the shelling-out mechanism, the phpcs.xml fallback to Magento2 on app/code, the deliberate skipping of phpstan/rector when no config exists (and why no safe fallback), severity assignments per check, scope='vendor' vs 'app_code' tagging, and the scanned=false-with-reason contract.

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 single dense paragraph is front-loaded with the overall purpose before enumerating the seven checks, and virtually every sentence carries distinct behavioral information with no filler. It is very long, but for a tool with seven heterogeneous checks the length is largely earned rather than 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?

Given the complexity, an output schema exists so return shape needn't be explained, yet the description still covers scanned=false handling, severity semantics, and scope tagging. Nothing an agent needs to invoke and interpret this tool 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?

A single parameter with 100% schema description coverage: the schema already documents 'path' as the project root holding composer.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?

States a precise verb+resource: scans a Magento project's custom code for phpcs/phpstan/rector violations plus four additional non-obvious checks (vendor_phpcs, object_manager_misuse, core_overrides, dangling_references). It enumerates each check and its scope, so an agent can distinguish this from sibling tools like audit_security or build_upgrade_plan.

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

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

Usage is implied through the severity/blocker semantics (core_overrides errors feed build_upgrade_plan; warnings do not) and the vendor vs app_code scope split, which tells the caller which findings are actionable. However, it never explicitly states when to run this versus audit_security or the other sibling tools, nor any prerequisites beyond a project path.

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