Fleet overview

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

With no annotations, the description carries the burden and provides valuable behavioral details: it fetches devices, groups, and blueprints concurrently; notes the device total includes both macOS and iOS/iPadOS (not just Macs); and states that partial failures are reported individually. These go beyond the name and help set expectations, though it omits auth/rate-limit details.

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 two sentences, front-loaded with the main summary, and every clause adds value: the caveat about device totals prevents misinterpretation, and the failure-mode note clarifies behavior. No fluff 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 read-only aggregation tool with no output schema, the description covers what data is returned, how it behaves (concurrent fetching), and important caveats (cross-platform total, partial failures). It does not describe return formatting or default values, but those are partially in the schema, and the complexity is well addressed for an overview 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?

The input schema already has 100% coverage with detailed descriptions for both parameters (topGroups and staleThresholdDays). The description adds only indirect hints (e.g., 'stale check-ins' relates to staleThresholdDays) but does not need to compensate given the schema's thoroughness. 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 clearly states the tool's purpose as a 'one-call fleet summary' and enumerates specific data it provides (device counts by platform/OS, managed status, stale check-ins, device-group breakdown, blueprint states). It distinguishes itself from sibling tools like findDevices or listBlueprints by positioning it as an aggregated overview rather than a raw listing.

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 phrase 'one-call fleet summary' implies using this tool when you need a broad overview instead of making multiple find/list calls. It does not explicitly name alternative tools or state when not to use it, but the context is clear enough to guide selection.

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