check_updates

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

With no annotations the description carries the full burden and largely meets it: it discloses the two independent signals, the per-package verdict vocabulary ('ok', 'blocks', 'unknown'), a Rector dry-run, and the three-tier requirement resolution order (cache, live fetch, offline fallback) with the result reporting which was used. What it omits is the safety/cost profile — a Rector dry-run can be slow, and it never states the tool is a read-only analysis.

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 both sentences carry real information rather than padding. The first sentence is long and dash-heavy, but it is dense with substance 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 formatting is not the description's job, and the description nonetheless explains the semantic meaning of the key fields. For a 3-required-param tool with zero annotation and zero schema-description coverage, the remaining gap is parameter formats and runtime cost, which keeps it short of full marks.

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

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

Schema description coverage is 0%, so the description must compensate and it largely does not: path, target_php, and target_magento are never given formats, examples ('8.2', '2.4.7'), or path requirements. The narrative implies target_php/target_magento are versions, but that is inference, not documentation.

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

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

It states a specific verb and resource ('Checks the given Magento project against a target PHP and Magento version') and even enumerates the two computed signals. The scope is unmistakable, but it never names or differentiates itself from siblings such as upgrade_plan or module_risk, which an agent choosing between five upgrade-related tools would want.

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: a compatibility pre-check is plausibly what you run before upgrade_plan, but the description never says 'use this when...' or excludes an alternative. It spends its words explaining what the result contains rather than when to reach for the tool.

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