build_fleet_overview

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.