get_dfw_policy

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by describing the return shape ('Returns one policy object, not an envelope') and listing the included fields (category, sequence_number, stateful, scope, rule count). It also warns against passing a display name, which is a practical behavioral constraint not captured in annotations.

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 well-structured: a leading [READ] tag, purpose sentence, return detail, usage flow, then an Args section. Every sentence contributes necessary information without fluff. It front-loads the key purpose and keeps the overall length tight given the lack of schema descriptions.

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?

With no output schema, the description compensates by explaining the return format and key fields. It covers the full usage flow (list to single, then rules), input parameters, and response shape. For a straightforward get-by-id tool with two parameters, this is complete and leaves no major gaps.

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 0%, so the description carries the full burden of parameter meaning. It clearly explains policy_id with an example ('app-tier-policy') and target as 'Optional NSX Manager target from config.' Both parameters are adequately described beyond the bare schema types.

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 begins with '[READ] Get full details of a single DFW security policy,' which clearly states the action (get) and resource (single DFW policy). It distinguishes from siblings by emphasizing 'single' versus list_dfw_policies, and implies read-only versus create/delete/update. The return-format note ('one policy object, not an envelope') further clarifies the tool's specific behavior.

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 explicitly instructs when to use: 'Use it once list_dfw_policies has narrowed to one id — never a display name.' This both gives a workflow trigger and a clear exclusion. It also tells the next logical call ('Then call list_dfw_rules for the rules inside'), providing complete usage context.

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