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

Goes well beyond the annotations by disclosing the credit cost (2 credits, charged only on success) and a concrete rate limit of 100 req/min per API key. The annotations already establish this is a non-destructive, non-read-only, closed-world call, and the description fills in the billing and throttling behavior an agent needs to plan calls.

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?

Three short sentences, front-loaded with what the tool produces, followed by cost and rate limit. Every clause carries information and nothing is redundant.

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?

Without an output schema, the description compensates by enumerating the report's contents for both modes, and it covers cost and rate limits. It omits any mention of latency or whether report generation is synchronous versus polled (a sibling get_scan_status exists), which is the main remaining unknown.

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 only one parameter and schema coverage is 100%; the schema itself already says 'omit for the whole-organization report.' The description restates that same semantic without adding format, normalization, or validation details, so it lands at the baseline where the schema does the work.

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?

Uses a specific verb ('Compile') with a clearly enumerated payload for both the single-site and organization-wide variants, so the agent knows exactly what comes back. It does not, however, differentiate itself from the sibling get_site_report, which appears to overlap on the single-site case.

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 implicitly tells the agent how to select the org-wide mode ('or the whole organization'), but never states when to prefer this over get_site_report, get_improvement_plan, or find_issues, nor any prerequisite such as a completed scan. Usage has to be inferred from the field list.

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