Report servers and plugins to the team

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

With annotations already declaring openWorldHint=true and destructiveHint=false, the description still adds substantial context: the exact data that leaves the machine, an explicit exclusion list ('never paths, arguments, environment, headers or secrets'), the admin-side fleet-visibility prerequisite, and the preview-before-send workflow. This is exactly the kind of disclosure an agent needs for an outward-facing send operation.

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 preview/send distinction is front-loaded in the first clause, and the parenthetical payload enumeration is long but each item carries real information about what is transmitted. It is dense rather than padded, though the single-sentence structure with nested commas takes effort to parse.

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?

There is no output schema, and the description compensates well by describing the preview contents, so an agent knows what to expect from a dry run. The only real gap is project_dir, which is neither required nor described anywhere, leaving its role to be inferred from the name.

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 50%: confirm_send is documented in the schema, but the description reinforces it by tying 'true' to the human-agreement step ('after the user has seen the preview and agreed'), which is meaningful behavioral text beyond the schema. project_dir is left entirely unexplained in both schema and description, which keeps this below a 5.

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 names a specific verb and resource ('shows exactly what a fleet report would send') and clearly separates the two modes: preview by default, actual transmission with confirm_send=true. The enumerated payload contents (server names, scopes, transport, package names/versions, remote hostnames, plugin names/versions) make it distinguishable from siblings like export_bom or team_status without opening the 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 explicit gating conditions: 'Only when the user asks,' 'after the user has seen the preview and agreed,' and 'if the admin turned fleet visibility on.' That is strong when-to-use guidance, but it never names an alternative sibling (e.g., export_bom for a full BOM) or states when this should not be used instead of them.

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