ad_get_gpo_report

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

With no annotations at all, the description carries the full behavioral burden and mostly does not: it implies read-only via the '[READ]' tag but says nothing about required AD permissions, whether the report is generated locally or from a DC, output size/expense, or failure modes for a missing GPO. It also doesn't mention what the 'correlation_id' does.

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?

Very short and front-loaded with domain and access-mode tags before the action, so it scans quickly. It borders on under-specification given the low schema coverage, and mixing Portuguese body text with English tags is slightly inconsistent.

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?

An output schema exists, so return values need no explanation, and the basic action is understandable. But for a tool with zero annotation coverage and zero parameter documentation, missing identity format, correlation_id purpose, and a sibling-differentiation note leaves real gaps an agent must guess at.

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 0%, so the description must compensate. It does clarify that report_type accepts XML or HTML (valuable, since the schema gives only a bare default of 'xml' with no enum), but it leaves the required 'identity' parameter and 'correlation_id' completely unexplained, so most of the parameter set is still opaque.

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 gives a concrete verb+resource ('Gerar relatorio ... de GPO') plus the output formats, so an agent can tell this generates a GPO report rather than fetching a GPO. However, it does not distinguish itself from the near-identical sibling ad_generate_gpo_report, which an agent could easily pick instead.

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?

There is no statement of when to use this versus ad_get_gpo, ad_generate_gpo_report, or ad_compare_gpos, and no preconditions (e.g., whether identity must be a GPO name or GUID, or whether a domain must be specified). Only the '[READ]' tag hints at context.

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