policy_lookup

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

With zero annotations, the description carries the full burden and delivers: it discloses that it proxies a FortiGate monitor API through FortiManager, is a query against the currently installed policy, that `package` is informational and not sent, and that `matched` may be None because only the no-match case is documented. It also flags that positive-match field sets are passed through unreshaped, avoiding overpromising.

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?

Purpose is front-loaded, and Args/Returns/Example structure makes it skimmable. It is somewhat verbose in places — the How-To Guide meta-commentary on protocol/protocol_number and the repeated package_hint caveat could be trimmed without losing information.

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?

Covers everything an agent needs for a 9-param, 9-field-output tool: parameter semantics, required vs optional behavior, return-shape caveats, and a worked example. It over-delivers by documenting the return dict even though an output schema exists.

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, and it documents all 9 params: protocol with concrete enum values (6=TCP, 17=UDP, etc.), the "device[vdom]" suffix convention, which fields are omitted when unset and the device-default implications, and the subtle package/package_hint distinction. This adds substantial meaning beyond the bare schema.

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?

Opens with a specific verb+resource ("Simulate a firewall policy lookup for a traffic 5-tuple against a managed device") and clarifies the semantics: which policy would match this traffic right now, on the currently installed package. This meaningfully separates it from the many config-oriented policy siblings (get_firewall_policy, list_firewall_policies, search_firewall_policies), though none is named explicitly.

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 use case (test a traffic tuple against the live device, like the UI's Policy Lookup dialog) is clearly conveyed, but there is no explicit when-not or named alternative (e.g., "use X to inspect policy config, use this to test matching"). It says it takes no policy-package argument but doesn't explain what to do instead when a specific package must be tested.

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