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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial non-obvious behavior: sign-in reads create no file and send no report_name, filtered role queries may return cached Oracle data, saved reports are snapshots of unknown age, cell-level/log fields are omitted, Oracle text must be treated as data (injection warning), and application-restricted policies are refused. These are exactly the traits an agent could not infer from annotations or schema.

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 purpose is correctly front-loaded, but the body is a chain of clipped, telegraphic clauses with ambiguous referents — 'Old and new cell values, logs and arbitrary fields are omitted' does not say omitted from what, and 'sends no report_name and create no file' mixes the schema field name with prose. Every sentence carries information, but the structure reads as compressed notes rather than a coherent guide.

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 14-parameter, five-action tool with no output schema, the description covers the important gaps: what is not returned, staleness of snapshot data, policy restrictions, and that the documentation link exists. It still leaves per-action return shapes and how the actions relate to the export workflow implicit, which an agent must infer.

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%, so all 14 parameters are already documented, and the baseline of 3 applies. The description does add a little linkage ('sign-in reads send no report_name' implying fileName is not used for sign_ins; filtered vs unfiltered userLogin/groupName behavior; caller-supplied exportedAt), but it does not map guidance to parameters by name, so the added value over the schema is marginal.

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 opening sentence gives a specific verb (read) and enumerates the exact resources covered: user/group role reports, sign-ins, job status and report metadata from a CSV/ZIP. It is clearly distinct from export_access_report (which generates) and read_audit_changes. It loses a point because the 'report job's status' portion overlaps ambiguously with siblings like check_job_status and get_job_details, with no differentiation.

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?

Provides real decision context: 'Use it for access reviews without changing users or roles,' plus a conditional guidance ('use an unfiltered query for updated data' when filtered results may be stale) and the constraint that 'this pod-wide tool refuses application-restricted policies.' It stops short of naming alternatives explicitly, so the agent is not told where to go when this tool refuses a policy or when a fresh export is required.

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