fortigate-mcp-server

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

With no annotations, the description carries the full burden and does so well: it discloses the reboot side effect, that credentials come from environment variables rather than arguments, the auth mode required, and the meaning of FortiCare error 10. These are exactly the operational facts an agent needs before invoking a mutation.

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?

Front-loaded with the action and mechanism, then prerequisites and error semantics. Every sentence earns its place, though the error-10 sentence is somewhat tangential to selecting and invoking the tool.

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 no-annotation, no-output-schema mutation tool, the description covers the critical behaviors: side effect, auth requirements, credential sourcing, and a common failure mode. It stops short of describing the response or idempotency, which are minor 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 coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that FortiCloud credentials are sourced from env vars and never from arguments, and it reinforces that confirm triggers a reboot, which the schema already notes.

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?

States a specific verb and resource ('Activate the free permanent evaluation license on an unlicensed FortiGate-VM') and explains the mechanism (FortiCloud login, same call the GUI makes). It is clearly distinguishable from siblings like get_license_status or get_license_limits.

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?

Gives clear conditions: use on an unlicensed/fresh VM, and use session auth because unlicensed VMs refuse most API calls. It does not explicitly name sibling alternatives or state when NOT to use it, but the preconditions are concrete enough to route the agent correctly.

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

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

With no annotations, the description carries the full burden and does well: it discloses evaluation order (top-down), the built-in catch-all pass rule, the default top insertion and how to override it, and the blast radius (only policies whose application_list is this profile). It omits persistence/auth requirements and any return-value expectations, but the behavioral core is unusually rich.

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 tight sentences with no filler, and the default-position behavior is front-loaded alongside the scope constraint. Density is high but each clause earns its place.

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 mutation tool with no annotations and no output schema, the description covers evaluation semantics, insertion behavior, and effect scope well enough to call it correctly. Minor gaps remain around permissions and result format, but nothing critical is missing.

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 already 100%, so the baseline is 3, but the description adds genuine meaning: it explains why position defaults to top (rules evaluate top-down above the catch-all pass rule) and clarifies that applications/categories accept names or ids. That is more than the schema's terse field descriptions.

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?

States a specific verb (add) and resource (a rule to an app-control profile) with the matching criteria (applications and/or categories by name or id). It is immediately distinguishable from the delete_app_control_rule sibling without opening either schema.

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 explains rule behavior (top-down checking, insertion at top by default, position=bottom to append) which implies how to use it, but never states when to reach for this tool versus alternatives like delete_app_control_rule or list_app_control_profiles. Usage is inferable rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one real trait beyond the schema: the reserved IP may fall outside the DHCP pool. However, it omits permission requirements, idempotency/duplicate handling, and what a successful call returns, which matters for a mutation tool.

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?

A single front-loaded sentence that states the action first and appends one clarifying constraint in parentheses. No filler or redundant restatement of the tool name.

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 mutation tool with no annotations and no output schema, the description covers the core action and one nuance but leaves failure modes, permissions, and duplicate handling unaddressed. Given the fully documented parameters, this is adequate but not complete.

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 five parameters (ip, mac, vdom, server_id, description) are already documented in the schema. The description only restates mac/ip/server implicitly and adds no format, default, or constraint detail beyond what the schema provides, so the baseline 3 applies.

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 specific verb (Reserve) plus resource (IP for a MAC address on a DHCP server), and the parenthetical clarifies the scope of what can be reserved. It is immediately distinguishable from the sibling delete_dhcp_reservation and from list_dhcp_servers/list_dhcp_leases.

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?

Usage is implied by the name and description (create a fixed DHCP reservation), but there is no explicit statement of when to prefer this over alternatives, no prerequisites, and no note about behavior when a reservation for the MAC/IP already exists. The parenthetical about the IP sitting outside the pool is a useful scope hint but not usage routing.

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

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

No annotations are provided, so the description carries the full burden. It does disclose one real behavioral constraint beyond the schema ('Wildcard (*) hostnames are rejected by FortiOS'), which is useful. However, for a mutation tool it omits permissions, whether the zone must pre-exist, reversibility, and error behavior.

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?

Two short sentences with zero waste, and the core purpose is front-loaded ahead of the constraint. Every sentence earns its place.

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 mutation tool with 8 parameters, no annotations, no output schema, and 50% schema coverage, the description is far too thin. It should at minimum clarify prerequisites, parameter semantics, and expected effects of the write.

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 only 50%, so the description must compensate for undocumented parameters (ip, ttl, ipv6, hostname) — and it does not. It adds no parameter meaning at all, leaving half the parameters with no explanation in either the schema or the description.

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 states a specific verb+resource: 'Add a record to a local DNS zone.' This is clear and distinct from sibling DNS tools like create_dns_zone, delete_dns_record, or list_dns_zones. It lacks explicit sibling differentiation, so it falls short of a 5.

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?

No guidance on when to use this versus alternatives, no prerequisites (e.g. whether the zone must already exist via create_dns_zone), and no mention of related operations like delete_dns_record. The only constraint given is a data-validation rule, not usage context.

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

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

With no annotations, the description carries the full burden and does so well: it declares the operation read-only, discloses a genuine side effect (the hash check reads a config backup, which the FortiGate logs as a config download), and describes the return shape (findings graded critical/warn/info with a suggested fix). These are behavioral traits beyond any structured field.

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?

Front-loaded with the scope, followed by return shape, then the side-effect caveat with its opt-out. It is dense and long, but every sentence carries distinct information (checks, return format, side effect) rather than padding, so the length is earned by the tool's breadth.

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?

No output schema exists, so the description supplies the return semantics (graded findings with suggested fixes). Both parameters are accounted for (vdom via schema, check_hashes via schema plus description detail), and the one non-obvious behavioral caveat is disclosed. Nothing needed to invoke it correctly is missing.

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 100%, so the schema already documents both parameters (baseline 3). The description adds real semantic value beyond the schema by explaining the why and consequence of check_hashes (it triggers a logged config download) that the raw schema does not convey. The vdom parameter is left to the 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?

States a specific verb+resource ('Read-only audit of how the FortiGate can be administered') and then enumerates the exact checks (trusted hosts/MFA, default admin, API keys, WAN admin access, local-in policies, legacy SHA-256 hashes). The scope is clearly admin-access focused, distinguishing it from audit_hardening and audit_policy_protection, which an agent can infer even though they aren't named.

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 usage guidance for one parameter (set check_hashes=false to avoid the logged config download) but never says when to choose this audit over the sibling audits (audit_hardening, audit_policy_protection). Usage context is implied by the enumerated checks rather than explicitly framed as when/when-not.

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

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

With no annotations, the description carries the full burden, and it does well: it declares read-only behavior, that each finding carries a fix order and a 'can cut off admin access' warning, that fix_plan lists them in that order, and how behavior differs on the evaluation license. It omits permission/authentication requirements, which is the main remaining gap for a tool of this scope.

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?

Front-loaded with the purpose before the enumeration, and every clause names a concrete check area rather than filler. The single very long sentence and dense comma-list make it less scannable than it could be.

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?

No output schema exists, so the description must convey return shape, and it does: per-finding remediation ordering, the admin-cutoff flag, the fix_plan ordering, and license-specific annotations. For a two-param read-only audit, nothing an agent needs to invoke it correctly is missing.

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 100% with only two parameters, so the schema already documents vdom and check_hashes. The description adds a modest clarification that check_hashes reads a config backup 'as in audit_admin_access', but nothing beyond baseline for vdom.

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?

States a specific verb+resource ('Read-only hardening audit') and then enumerates the exact check areas covered, from local-in and telnet through HA heartbeat. It explicitly positions itself relative to the sibling audit_admin_access ('everything audit_admin_access checks, plus...'), so an agent can tell which audit tool is the superset.

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 'everything audit_admin_access checks, plus...' framing implies this is the comprehensive option versus the narrower sibling, and the eval-license note gives a situational caveat. It does not, however, explicitly state when NOT to use it or name audit_policy_protection as the narrower alternative for policy-profile checks.

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

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

With no annotations, the description carries the full burden, and it does disclose the key trait ('Read-only') plus the precise detection semantics that determine what the tool reports. It does not mention permission requirements or rate behavior, but the safety profile and detection scope are well covered.

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 check scope is front-loaded and the long enumerated clause is dense but each item earns its place by telling the agent what the audit surfaces. 'Read-only' is efficiently separated at the end.

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 no-output-schema audit tool, the description conveys enough about scope and detection targets for correct invocation. It could say more about what the results look like, but the coverage of what is audited is strong.

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% and the only parameter (vdom) is fully documented in the schema, including its default. The description adds nothing about the vdom parameter, so the baseline 3 applies.

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?

States a specific verb ('Check') and resource ('accept policies are actually protected') and then enumerates the exact misconfigurations it detects (WAN traffic without IPS, disabled profiles, HTTPS-blind inspection, unlicensed FortiGuard, missing logging). This clearly distinguishes it from sibling audit tools like audit_admin_access and audit_hardening.

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 implies the tool's role (security-posture auditing of firewall policies) and flags 'Read-only', but never states when to reach for it versus the other audit tools or list_firewall_policies/get_policy_stats. Usage must be inferred from scope rather than stated.

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

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

With no annotations, the description carries the full burden and discloses key behaviors: writes to a local file, returns path and size, does not return the config text itself, and is allowed in read-only mode. It omits edge cases like file overwrite behavior or failure handling, but covers the essential behavioral traits well.

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 tightly written sentences, front-loaded with the core action and output, followed by permission context and the rationale for not returning text. Every sentence earns its place with no redundancy.

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 simple two-parameter tool with no output schema, the description explains the return values (path and size) and the key constraint that the config text is not returned. Minor gaps such as overwrite behavior or error cases exist, but overall it provides enough context for an agent to invoke correctly.

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 the schema already documents both optional parameters. The description adds no parameter-specific syntax or format details beyond the obvious 'local file' reference, matching the baseline for high schema coverage.

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?

States a specific verb ('Back up') and resource ('full running configuration'), and clarifies the output is a local file path and size rather than config text. This clearly distinguishes it from all read/list/delete siblings.

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 implies usage through its purpose and notes 'Allowed in read-only mode', but does not explicitly say when to use it versus alternatives or offer exclusions. No alternative backup tool exists among siblings, so implied usage is sufficient, but explicit guidance is absent.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about write semantics, permissions, duplicate-name behavior, or what the VDOM default means. For a mutation tool with zero annotation coverage, this is a significant gap.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly the same under-specification reflected elsewhere.

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 create tool with eight parameters, a nested `extra` object, no annotations, and no output schema, the description omits the response shape, error/duplicate behavior, and any mention of the passthrough `extra` attribute. It covers the resource shape but leaves the agent without enough to call it confidently.

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 the schema already documents all eight parameters, including the subnet/FQDN/range distinction. The description's enumeration of the three address forms largely restates the schema, so the baseline 3 applies.

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?

States a specific verb and resource ("Create a firewall address") and enumerates the three supported forms (subnet/host, IP range, FQDN), so an agent can distinguish it from siblings like create_address_group. It does not explicitly name the alternative tools, but the resource itself is unambiguous.

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?

No when-to-use context, prerequisites, or exclusions are given. The address-form enumeration implies which parameter set applies, but nothing tells the agent when to choose this tool over create_address_group or update_address.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing beyond the name. It does not state whether the operation is idempotent, what happens on duplicate names, which permissions are needed, or how the VDOM parameter affects behavior.

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?

One short sentence with no filler, which is appropriately front-loaded, but the extreme brevity reflects under-specification rather than disciplined conciseness.

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 mutation tool with no annotations and no output schema, the description is inadequate: it omits required-parameter expectations, VDOM/default behavior, and the arbitrary 'extra' attribute merging. The schema covers parameters, but nothing covers the tool's behavioral contract.

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 every parameter (name, vdom, extra, comment, members) is already documented in the schema; the description adds no extra meaning. Baseline 3 applies when the schema does the heavy lifting.

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 states a specific verb (Create) and resource (address group), so an agent immediately knows the operation. However, it offers no differentiation from nearby siblings such as create_address, create_service_group, or update_address_group.

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 guidance on when to use this tool versus the many other create/update tools, no prerequisites, and no note about required inputs. The agent must infer everything from the schema alone.

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

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

No annotations are supplied, so the description carries the full disclosure burden. It adds genuinely useful behavioral context (the wildcard restriction, the internal-vs-public view semantics), but says nothing about idempotency, behavior on a duplicate zone, permissions required, or what is returned.

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 the core action, then two operational caveats. No filler; each clause carries information an agent needs.

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 an 8-parameter creation tool with a nested records array, no annotations and no output schema, the description covers the notable FortiOS quirk and the view flag. It leaves gaps around failure modes, duplicate handling, and what a successful call yields, which matters more here because annotations provide no safety profile.

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 every parameter is already documented, including ttl defaults, vdom, authoritative, and the nested record fields. The description's view=shadow remark largely restates the schema's own 'shadow (internal, default) or public' text, so it adds little beyond the baseline.

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?

States a specific verb+resource ('Create a local DNS zone'), which cleanly distinguishes it from siblings like list_dns_zones, delete_dns_zone and add_dns_record. It stops short of explicitly naming those alternatives, but the action is unambiguous.

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 hints at selection context by explaining that view=shadow serves internal clients, and warns that wildcard hostnames must be expanded into per-name records. It never says when to create a zone versus adding records to an existing zone, nor what prerequisites (existing VDOM, DNS profile) apply.

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

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

With no annotations, the description carries the full burden and does disclose two non-obvious traits: new policies are appended to the end of the list, and evaluation licenses cap at 3 policies. It omits permissions, error behavior on name collision, and idempotency, but the constraints it does surface are valuable.

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, each earning its place: purpose, ordering behavior plus alternative, and license constraint. The core action is front-loaded with zero filler.

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 21-parameter mutation tool the schema is fully self-documenting on inputs, and the description adds the key operational caveats (append ordering, license cap). It lacks return-value guidance (no output schema exists, e.g. the resulting policyid) and permission requirements, but is otherwise adequate.

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 21 parameters (including the nested 'extra' object) are already documented in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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?

States a specific verb and resource ("Create a firewall policy") and immediately distinguishes itself from the sibling move_firewall_policy, which handles reordering. An agent can identify this as the creation path without opening any schema.

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?

Explicitly routes reordering to move_firewall_policy and warns about the 3-policy cap on FortiGate-VM evaluation licenses, which are genuine when-to-use signals. It stops short of stating prerequisites (required VDOM, permissions) or when not to create, so it is clear but not exhaustive.

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

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

With no annotations, the description carries the full burden and does well: it discloses the license constraint, the VIP-only-vs-ordinary-address restriction, and the destructive side effect that replace_destinations makes old destinations unreachable. It omits auth/permission requirements and error/idempotency behavior, so it is not complete.

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?

Four dense sentences, front-loaded with the core mapping and with no filler; each sentence contributes required context. Scannability suffers slightly from parentheticals and semicolons, but 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?

For a 12-parameter, nested, no-annotation mutation tool, the description covers the behavioral and workflow context an agent needs to call it correctly. It does not describe the response shape, and there is no output schema to compensate, leaving a minor gap.

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 100%, so the schema already documents all 12 parameters (baseline 3). The description adds genuine meaning beyond the schema for the two most consequential params: the purpose of attach_to_policy and the destructive consequence of replace_destinations, plus the note that services match the mapped internal port.

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 first sentence states a specific verb (Create) and resource (port forward / VIP) and immediately defines the traffic mapping semantics. It clearly distinguishes this from list_port_forwards/delete_port_forward and from create_firewall_policy by describing the VIP-plus-policy relationship.

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 gives strong conditional guidance: use attach_to_policy to reuse an existing policy because the eval license allows only 3, and pass replace_destinations=true only when the target policy already uses only VIPs. It stops short of explicitly naming the alternative tool (create_firewall_policy) for the new-policy path.

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

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

No annotations are provided, so the description carries the full behavioral burden. It only implies a write operation via 'Create' and does not describe permissions, side effects, validation behavior, or how the new service can be used afterward.

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?

It is a single front-loaded sentence with no wasted words. For its length, it is as concise and structured as possible.

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 mutation tool with no annotations and no output schema, the description is too thin. It does not cover usage context, required permissions, side effects, or how the created service integrates with firewall policies or service groups.

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 parameter meanings are already well documented in the schema. The description adds only the overarching TCP/UDP context and does not contribute parameter-level detail beyond what the schema provides.

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 states a specific verb and resource: create a custom TCP/UDP service. It clearly identifies the object being created, though it does not distinguish this tool from sibling create tools such as create_service_group or create_address.

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 guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. The agent must infer that this is for standalone custom services rather than service groups.

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

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

With no annotations, the description carries the full behavioral burden. It adds genuinely useful context (the evaluation license's 3-policy limit motivating group creation) but omits operational traits: required permissions, whether members must already exist, failure behavior, or idempotency.

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?

Front-loaded with the verb and resource, then a compact example and a one-line rationale. No filler, though the license-limit sentence is context rather than strictly necessary to invoke the tool.

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 5-param create tool with no annotations and no output schema, the description covers purpose and the members example but leaves the 'extra' passthrough object, vdom defaulting, and mutation outcomes unexplained. Adequate but with clear 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 coverage is 100%, so the baseline is 3, and the example adds meaning beyond the schema by illustrating the shape of both required params (name = group label, members = list of service/group names). It does not explain the vdom or extra parameters, but the example lifts it above baseline.

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?

States a specific verb and resource (create a service group) and reinforces it with a concrete example (K3S-MGMT = [SSH, K8S-API, PING]). It is distinguishable from create_service (a single service) and create_address_group, though it never names a sibling 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?

It gives a rationale for when to use grouping (covering several services with one policy under the 3-policy license limit), which implies usage. However it never states when NOT to use it or points to alternatives like create_service or update_service_group, leaving the agent to infer the routing.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the eval-license route cap, a genuine operational constraint, but says nothing about required permissions, whether the change is immediately active, or what happens on exceeding the limit.

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?

Two short sentences, front-loaded with the action and followed by the most consequential constraint. Minimal waste, though the license note is terse enough to be slightly ambiguous about what happens when the limit is hit.

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?

A mutation tool with no annotations and no output schema. The schema fully documents inputs, and the license cap is a useful addition, but the description leaves behavioral gaps (permissions, activation, error behavior on exceeding the limit) that an agent might need.

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 7 parameters including dst, device, vdom, and the nested 'extra' object are already documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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?

'Add a static route' gives a specific verb (create) and resource, unambiguous against siblings like delete_static_route and list_static_routes. It doesn't explicitly differentiate from those siblings, but the verb makes the distinction self-evident.

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?

No explicit when-to-use or alternatives, but the second sentence encodes a real usage constraint: evaluation licenses cap routes at 3, which affects whether the call will succeed. That is implied guidance rather than a full when/when-not statement.

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

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

With no annotations, the description carries the full burden. It usefully discloses the dependency failure mode (a policy or group reference blocks deletion), which is the highest-risk behavior for this tool. However, it omits permission/auth requirements, whether the call is idempotent on a missing name, and whether success returns anything — gaps that matter for a destructive operation with zero annotation coverage.

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?

A single front-loaded sentence naming the action and target, with the constraint in a compact parenthetical. Every clause earns its place and nothing is wasted.

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 two-parameter delete tool with full schema coverage and no output schema, the description supplies the one piece of context an agent genuinely needs before calling — the reference dependency that causes failure. It is nearly complete, missing only auth/idempotency notes.

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% for both parameters ('name' and 'vdom'), so the schema already documents them fully. The description adds no syntax, naming convention, or default details beyond what the schema provides, so the baseline 3 applies.

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?

States a specific verb ('Delete') and a precise resource ('a firewall address'), which cleanly separates it from delete_address_group, delete_firewall_policy, and delete_static_route in the sibling list. An agent can identify the target object type without opening the schema.

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 parenthetical establishes one real precondition ('fails while a policy or group still uses it'), which implicitly tells the agent to detach references first, but no alternatives or when-to-use routing is given (e.g., delete_address_group for groups, update_address to modify instead). Usage is inferable but not explicit.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the failure condition tied to policy usage, but says nothing about irreversibility, required permissions, or what happens to group members on deletion.

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?

A single tight sentence with zero waste, front-loading the action and appending the key constraint.

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 simple two-parameter delete tool with no output schema this is minimally adequate; it identifies the target and one constraint, but a delete operation with no annotation coverage would benefit from noting irreversibility or permission requirements.

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% with only two parameters (name, vdom), both documented in the schema. The description adds no syntax, format, or defaulting detail beyond what the schema already provides, so baseline 3 applies.

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 states a specific verb+resource ('Delete an address group'), which clearly distinguishes it from the many other delete_* siblings (delete_address, delete_service, delete_dns_zone). It is precise but does not explicitly name alternatives.

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 parenthetical 'fails while a policy still uses it' is an implied precondition that tells the agent when the call will be rejected, but it never states when to prefer this tool over alternatives or what to do first (e.g., remove the group from the policy).

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Remove' signals a destructive mutation, but the description does not disclose permissions, reversibility, failure behavior, or side effects.

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?

It is a single front-loaded sentence with no wasted words. The essential action, resource, and id prerequisite are all communicated efficiently.

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 simple delete operation with full schema coverage, the description is adequate about what is deleted and how to identify it. With no annotations and no output schema, it should do more to disclose destructive behavior, permissions, or expected result.

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 the schema already documents id, profile, and vdom. The description adds only 'by its id' and a cross-reference for finding the id, which is marginal beyond the 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?

The description states a specific verb and resource: 'Remove a rule from an app-control profile by its id.' It distinguishes the operation from list/add siblings and points to list_app_control_profiles for the required id, though it does not explicitly name alternative tools or conditions.

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 parenthetical reference to list_app_control_profiles gives an implied prerequisite for obtaining the rule id. However, it does not explain when to choose this delete operation over alternatives or any conditions/exclusions.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Remove' implies a destructive mutation, but the description does not state whether deletion is permanent, whether it is idempotent on a missing id, what permissions are required, or what happens to related leases. For a delete tool with zero annotation coverage this is a substantial gap.

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?

A single short sentence with the action and target front-loaded and no wasted words. The trailing parenthetical is the only slightly loose element, but overall it is tight and scannable.

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 destructive mutation with no annotations and no output schema, the description omits the key context an agent needs: permanence, error behavior on unknown ids, and permission requirements. Fully covered schema helps, but the behavioral side is thin for a delete operation.

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%, with id, server_id, and vdom all documented in the schema, so the baseline is 3. The description adds only 'by its id' and does not clarify the required server_id/vdom relationship or id format beyond what the schema already states.

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?

States a specific verb (Remove) and resource (DHCP reservation) with the identifier ('by its id'), which cleanly separates it from add_dhcp_reservation, update_dhcp_server, and list_dhcp_leases. The parenthetical '(see list_dhcp_servers)' is a slightly imprecise pointer, since that tool lists servers rather than reservations, but the core purpose is unambiguous.

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 explicit when-to-use or when-not-to-use guidance and no mention of alternatives or prerequisites. The '(see list_dhcp_servers)' hint gestures at where to source the id but does not describe any selection condition. Minimal routing value.

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

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

No annotations are provided, so the description carries the full behavioral burden. It only states that a deletion occurs; it does not disclose irreversibility, required permissions, side effects, or any confirmation/error behavior expected from a destructive operation.

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?

A single front-loaded sentence with no wasted words. It efficiently conveys the action, target, and key identifier.

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 destructive tool with no annotations and no output schema, the description omits important behavioral context such as irreversibility, authorization expectations, and side effects. The pointer to list_dns_zones is also potentially misleading for obtaining a record id, since that sibling lists zones.

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 the schema already documents all three parameters, including the VDOM default. The description adds only a reference to list_dns_zones and does not supplement the meaning of id or zone beyond what the schema provides.

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?

States a specific verb and resource ('Delete a record from a local DNS zone'), names the key identifier ('by its id'), and implicitly distinguishes itself from sibling delete_dns_zone by operating on a record rather than a zone.

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?

Usage is implied by the tool name and description, and it points to list_dns_zones for context. However, it does not explain when to prefer this over related tools, nor does it clarify prerequisites such as needing the zone to exist or how to obtain the record id.

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

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

With no annotations, the description carries the full behavioral burden. It implies a destructive removal but never states whether the interface DNS config is deleted or just disabled, whether the change is reversible, whether it needs elevated permissions, or what confirmation/response follows.

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?

A single front-loaded sentence with no filler, which is appropriate for a simple two-parameter delete. It is efficient, though it is arguably too terse given what it omits.

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 destructive delete operation with no annotations, no output schema, and no usage guidance, this description is thin. It leaves the agent without any information on side effects, reversibility, or how it differs from the adjacent DNS tools.

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 the schema already documents both the vdom and interface parameters; baseline 3 applies. The description only echoes the interface concept and adds no format or default details beyond the 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?

States a specific action and resource: stopping DNS service on an interface, which is a clear verb+resource pair. It distinguishes itself from list_dns_servers and set_dns_server implicitly, though it never explicitly names them or delete_dns_zone as the sibling for a different object.

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?

No guidance on when to use this versus set_dns_server or delete_dns_zone, and no prerequisites or warnings are given. The agent must infer that this removes DNS service rather than merely listing or configuring it.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the cascading destruction of child records, which is genuinely useful and not in the schema, but it says nothing about irreversibility, required permissions, or confirmation semantics for what is clearly a destructive operation.

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?

One short sentence, front-loaded with the verb and resource, with the destructive scope folded in rather than buried. No filler.

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 destructive, zero-annotation tool with no output schema, the description covers effect scope but omits irreversibility, permission requirements, and failure behavior. Adequate but with clear gaps an agent would want before issuing a delete.

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 both 'name' and 'vdom' are already documented with meaning and defaults. The description adds no syntax, format, or selection guidance beyond that, so the baseline 3 applies.

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?

Specific verb (Delete) plus resource (local DNS zone) with an added scope note ('and all its records'). It is distinguishable from sibling delete_dns_record and delete_dns_server by the resource noun alone, though it does not explicitly name them.

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?

No when-to-use guidance, no prerequisites, and no alternatives cited. The cascade note implies the tool's effect but not when an agent should reach for it over delete_dns_record or list_dns_zones first.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it only restates the operation. It omits that deletion is destructive and irreversible, whether it requires admin rights, what happens to associated rules/references, and what the return looks like. Nothing beyond the verb is disclosed.

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?

A single, front-loaded sentence with no waste. It is appropriately sized but is arguably too terse for a destructive operation, which is a completeness concern rather than a conciseness one.

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 destructive delete tool with no annotations, no output schema, and no behavioral notes, the description is severely lacking. An agent cannot determine safety, reversibility, permissions, or side effects from this definition.

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%, with policyid and vdom both documented in the schema (including the VDOM default). The description adds no parameter detail, but the schema already does the heavy lifting, making the baseline 3 appropriate.

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?

States a specific verb and resource ('Delete a firewall policy'), which is clear and unambiguous on its own. However, it does not differentiate itself from siblings like update_firewall_policy or get_firewall_policy beyond the verb, and offers no scope detail (e.g. what a policy controls or what deletion entails).

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?

No when-to-use guidance, no prerequisites, no mention of alternatives. An agent gets zero help deciding between this and update_firewall_policy or move_firewall_policy.

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

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

With no annotations, the description carries the full behavioral burden and does it well: it discloses the failure condition (policy still references the VIP), the effect of detach=true (removes the VIP from every policy's destinations), and the hard blocker case (sole destination policy). It stops short of auth/permission or response details, but the destructive semantics are clearly conveyed.

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?

Front-loads the core action ('Delete a VIP') then layers the conditional behavior in three tight sentences. No filler, though the conditional clauses could be slightly denser.

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 destructive tool with no annotations and no output schema, the description covers the important edge cases (in-use refusal, sole-destination blocker) and the detach workflow. Missing only ancillary details such as permission requirements, which for this domain are minor.

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 the schema already documents name, vdom, and detach; baseline is 3. The description adds some behavioral meaning to detach ('removes it from every policy's destinations') but leaves name/vdom to the 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?

States a specific verb and resource ('Delete a VIP') that clearly identifies the operation. It maps to the port-forward VIP concept matching the tool name and its list_port_forwards/create_port_forward siblings, though it doesn't explicitly name those siblings.

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?

Gives concrete usage context: it tells the agent the delete will be refused while a policy uses the VIP, offers detach=true as the workaround, and warns that a policy whose only destination is this VIP blocks the delete. This is actionable pre-invocation guidance, though it is framed as prerequisites rather than as tool selection.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses a dependency failure mode (fails while a policy still uses it), but says nothing about irreversibility, required permissions, or the effect on references. For an unannotated destructive mutation this leaves meaningful gaps.

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?

One sentence, front-loaded with the action, with the parenthetical carrying only genuinely load-bearing failure information. No wasted words.

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 the essential dependency caveat for a delete tool, and the schema fully documents both parameters. However, with no annotations and no output schema, the description should also address irreversibility or auth requirements to be complete for a destructive operation.

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 both 'name' and 'vdom' are already documented in the schema. The description adds no parameter-level detail beyond that, making the baseline 3 appropriate.

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?

States a specific verb+resource ('Delete a custom service'), and the 'custom' qualifier helps separate this from predefined/built-in services and from the sibling delete_service_group. It does not, however, explicitly name the sibling it must not be confused with.

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 parenthetical gives an implied precondition (a policy must not still reference the service), which is useful usage context. There is no explicit when-to-use statement, no mention of the sibling delete_service_group or delete_firewall_policy, and no guidance on confirming intent before a destructive call.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the referential-integrity failure mode, which is real added value. However, it omits permission requirements, whether deletion is reversible, and confirmation behavior expected of a destructive operation.

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?

A single sentence that front-loads the action and parenthetically attaches the one constraint that matters. No filler, nothing to trim.

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 two-parameter destructive tool with a fully documented schema and no output schema, the description covers purpose and the key failure condition. The remaining gap is the safety/permission profile, which nothing else supplies given the absence of annotations.

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 both 'name' and 'vdom' are already documented in the schema, including the VDOM default. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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?

States a specific verb (Delete) and resource (service group), which is distinguishable from siblings like delete_service, delete_address_group, and delete_firewall_policy. It does not explicitly contrast itself with those siblings, but the noun phrase is specific enough to route correctly.

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?

Gives a concrete precondition for success: deletion fails while a policy still references the group. This tells the agent when the call will not work and implies it must detach policies first. It stops short of naming alternatives (e.g., update_service_group) or stating what to do instead.

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

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

No annotations are provided, so the description carries the full behavioral burden. It states that this is a delete but says nothing about irreversibility, whether a confirmation is required, permission needs, or what happens on an invalid seq_num.

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?

One sentence, zero filler, and the identifying selector is front-loaded. Nothing is wasted.

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 simple two-parameter delete with full schema coverage and no output schema, the description is adequate but thin. With no annotations to carry the destructive-operation profile, the missing disclosure of irreversibility and error behavior leaves a real gap.

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 both parameters are already documented. The description adds only the hint that seq_num originates from list_static_routes; it does not explain the VDOM parameter or validate constraints. Baseline 3 for full schema coverage applies.

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?

States a specific verb (Delete) and resource (static route) plus the exact selection criterion (sequence number). It is clearly distinguishable from its siblings list_static_routes and create_static_route.

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 parenthetical '(seq-num from list_static_routes)' implies an ordering workflow: list first, then delete by the returned identifier. However, there is no explicit when-to-use/when-not guidance, no mention of prerequisites, and no warning about consequences.

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

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

With no annotations, the description carries the full burden, and it does disclose the essential behavioral trait: this is a read-only schema introspection whose response varies in shape (table keyed by mkey vs. single settings object) and expands nested sub-fields when 'field' is supplied. It stops short of stating permission requirements, behavior for an unknown endpoint, or output size.

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?

Two sentences, front-loaded with the core purpose and then the drill-down behavior. The first sentence is dense with enumerated return content, but every clause contributes and there is no filler.

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?

There is no output schema and no annotations, so the description must explain results, and it does: response shape, field metadata, and nested expansion. Gaps remain around missing/unknown endpoint handling and any privilege or VDOM scoping caveats, but for an introspection tool this is close to complete.

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 endpoint and vdom semantics are already documented in the schema; baseline is 3. The description adds a modest amount for 'field' — that it returns the field in full including nested sub-fields — but gives no guidance on accepted endpoint path syntax beyond the schema's examples.

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 states a specific verb and resource ("Describe a configuration endpoint from the FortiGate's schema") and immediately clarifies what the answer contains: table vs. single settings object, plus field type/values/range/default. This implicitly separates it from value-returning siblings like get_config, but it never names or contrasts a sibling 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?

Usage is implied: use this to inspect the schema of an endpoint before reading or writing config, and pass 'field' to drill into one field. There is no explicit when-to-use/when-not or reference to alternatives such as get_config (current values), set_config (mutation), or search_api (discovery), leaving the routing decision to inference.

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

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

With no annotations, the description carries the full burden, and it does meaningfully disclose that only the public part is returned (implying the private key is never exposed) and what the return contains (PEM + SHA-256 fingerprint). It stops short of stating read-only/non-destructive nature, auth requirements, or error behavior.

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?

Two tight sentences with zero filler; the core action and its scope are front-loaded before the example and the return-value note.

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 correctly covers return values (PEM and fingerprint), and the schema fully covers the three parameters. It is nearly complete for a simple read tool, with only the safety/permission profile left implicit.

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 name, type, and vdom are already documented in the schema, including the type value list. The description only echoes the name example already present in the schema, adding no new parameter meaning.

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?

States a specific verb+resource ('Download a certificate's PEM') and scopes it precisely with '(public part only)' plus a concrete example (Fortinet_CA_SSL). An agent can distinguish it from list_certificates by the download/retrieve framing, though no sibling 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 description implies the use case ('so clients can be told to trust it') but never states when to use this versus list_certificates or get_interface-style siblings, and gives no prerequisites. Usage is inferable but not spelled out.

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

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

No annotations are provided, so the description carries the full burden and mostly succeeds: it discloses read-vs-write semantics (omit = report only), reversibility (false shows the step again), the persistence problem it solves, and the notable absence of a CLI equivalent. It does not mention permission requirements or what the call returns, which keeps it short of a 5.

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?

Four sentences, front-loaded with the action and immediately followed by the read-only default. The VM-eval rationale and the no-CLI note each add decision-relevant information rather than padding, though the explanation could be tightened slightly.

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 and no annotations, the description supplies the behavioral context an agent needs: default read behavior, both write directions, and the operational reason to use it. Only the return payload and any permission prerequisites are left unstated, which is acceptable for a two-parameter GUI toggle.

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% and both parameters are fully documented inline, so the baseline is 3. The description reinforces the omit-to-read behavior but adds no syntax, default, or format detail beyond what the schema already states for `hide` and `vdom`.

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?

States a specific verb pair (show/hide), the exact resource ('Migrate Config with FortiConverter' step of the FortiGate Setup popup), and the scope (GUI setup popup). No sibling tool covers this surface, and the description makes that unambiguous without opening the schema.

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?

Explains the trigger condition clearly: without `hide` it only reports state, and VM evaluation licenses are ineligible for FortiConverter so the step never completes and the popup recurs at every login until hidden. That tells the agent exactly when hiding is warranted. It stops short of framing alternatives, but no alternative tool exists, so the gap is minor.

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

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

With no annotations, the description carries the full burden, and it does disclose the FORTIGATE_READ_ONLY gate plus the /api/v2/ path requirement. However, for a tool that can issue POST/PUT/DELETE against arbitrary endpoints, it says nothing about destructive-operation warnings, permissions, or error behavior.

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?

Four short sentences, each carrying a distinct fact, with the core purpose and the sibling-routing rule front-loaded. Zero filler.

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 generic REST passthrough, the description covers the essentials an agent needs to invoke it correctly: path format, config-vs-monitor intent, read-only enforcement, and fallback routing. No output schema exists, so return values need not be explained, though it could say more about write safety.

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 the schema already documents all five parameters, setting the baseline at 3. The description adds path-prefix and cmdb/monitor semantics beyond the schema, but gives no extra meaning for method, body, vdom, or params.

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?

States a specific verb+resource: 'Call any FortiOS REST endpoint directly,' and explicitly positions itself against siblings with 'Prefer the dedicated tools when one exists.' An agent can immediately tell this is the generic escape hatch versus the many dedicated CRUD tools.

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?

Gives a clear routing rule (prefer dedicated tools) and distinguishes cmdb/... for configuration from monitor/... for live state, which directs endpoint choice. It stops short of stating explicit exclusions or edge cases, but the primary when-to-use condition is present.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a non-destructive read, but says nothing about required permissions, behavior when the name is absent, or whether VDOM scoping affects visibility.

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?

A single short sentence with no padding, and the operation is stated up front. It is efficient, though its brevity reflects under-specification rather than disciplined editing.

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 annotations and no output schema, the description should describe what is returned (the address object fields) and error behavior for an unknown name. Neither is covered, leaving an agent unable to anticipate the response shape.

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 both parameters (name, vdom) are already documented in the schema, including the VDOM default. The description adds no meaning beyond that, so the baseline 3 applies.

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 specific verb ("Get") and resource ("firewall address object") with the scope narrowed to a single object, which implicitly distinguishes it from the sibling list_addresses. It stops short of explicitly naming that alternative, so it is clear but not fully differentiated from its siblings.

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 tool versus list_addresses, get_firewall_policy, or any other retrieval sibling, and no prerequisites (e.g., that the address must already exist). Usage is only inferable from the word "one".

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

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

No annotations are provided, so the description carries the full burden; it does explain the data model returned (which MAC answers for which IP per interface), which is genuinely useful given no output schema exists. It is silent on read-only semantics, permissions, and pagination, but for a simple listing the content description is a reasonable partial disclosure.

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?

A single front-loaded sentence with no filler, stating resource and payload immediately. It is efficient, though its brevity is partly why usage guidance is absent.

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 two-optional-parameter read tool with 100% schema coverage and no output schema, the description adequately conveys what is returned. However, it omits any usage context or scoping notes, leaving the definition minimally viable rather than complete.

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 both the vdom and interface parameters are already documented in the schema, including the 'e.g. port2' example and the VDOM default. The description adds no parameter detail beyond this, which matches the baseline 3 when the schema does the heavy lifting.

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 names a specific resource (the IPv4 ARP table) and clarifies its contents as MAC-to-IP mappings per interface, which an agent can distinguish from siblings like get_routing_table or get_system_status. The verb is implied by the 'get_' name rather than stated, but the scope is unambiguous.

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 explicit when-to-use guidance, no mention of when this is preferable to alternatives such as get_routing_table or list_interfaces, and no prerequisites (e.g., VDOM context) called out. The agent must infer the use case entirely from the resource name.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely non-obvious behavior — password and key fields are returned as '<set>' rather than values — which is valuable beyond the schema. However it says nothing about permissions/authentication, output size or pagination, error behavior, or explicitly that the operation is read-only and non-destructive.

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?

Two tight sentences, zero filler, with the core capability (read any config endpoint, three modes) front-loaded and the redaction caveat appended where it is most useful.

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 generic config pass-through tool with no output schema and no annotations, the description covers the essential scope and the redaction behavior. It stops short of describing result envelope shape or whether large tables are truncated/paginated, which would help an agent plan calls.

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 five parameters (endpoint, mkey, vdom, filter, format) are already documented in the schema; baseline 3 applies. The description only restates the mkey idea ('one entry by mkey') without adding syntax, defaulting, or interaction rules among filter/format/vdom.

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?

States a specific verb ('Read') plus a broad resource ('any configuration endpoint') and enumerates the three read shapes (whole settings object, full table, single entry by mkey). This clearly separates it from set_config and describe_config among its siblings.

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?

Usage is implied by the verb and the three enumerated shapes, but there is no explicit when-to-use guidance and no mention of the neighboring siblings (describe_config for schema, set_config for writes, get_monitor for runtime data). The agent must infer the boundary.

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

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

No annotations are provided, so the description carries the full burden. It conveys no safety profile (read-only vs mutation), no return shape, and no auth/permission notes. The only behavioral hint is the noun 'settings,' implying a retrieval, which is weak for an unannotated tool.

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?

A single, front-loaded sentence with no filler; the defining clause follows immediately after the resource name. It is efficient, though it slightly under-specifies relative to its brevity.

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 one-parameter read with full schema coverage and no output schema, the description gives a hint about the returned content but no when-to-use context and no behavioral disclosure. It is minimally viable but leaves gaps an agent would need to close.

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% for the single vdom parameter, so the schema already documents it fully (default FORTIGATE_VDOM, usually root). The description adds nothing about the parameter, so the baseline of 3 applies.

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 identifies the resource (system DNS settings) and clarifies what those settings contain (upstream resolvers the FortiGate itself uses and forwards to), which helps distinguish it from list_dns_servers. However, it omits a leading verb and does not explicitly name the sibling it differs from, so an agent must infer the boundary between this and the DNS server list tools.

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 when-to-use guidance, no conditions, and no mention of alternatives such as list_dns_servers or get_system_status. The agent is left to guess whether this returns the FortiGate's own resolver config versus configured DNS servers for clients.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only restates the operation. It does not disclose error behavior for an unknown policyid, required permissions, VDOM resolution behavior, or what the returned payload contains.

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?

A single short sentence with the operation front-loaded and zero padding. It is appropriately sized for a simple getter, though it is arguably terse to the point of under-specification.

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 two-parameter read tool with full schema coverage and no output schema, the essentials are covered by the schema. Still, a getter should say what it returns and what happens on a missing policyid, neither of which is present.

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%, with policyid and the vdom default both documented in the schema, so the baseline is 3. The description adds no syntax, format, or lookup guidance beyond what the schema already supplies.

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?

States a specific verb (Get) and resource (firewall policy) with a scope qualifier (one), which distinguishes it from the plural list_firewall_policies sibling. However, it never names that sibling or otherwise differentiates itself from the other firewall_policy-family tools 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?

There is no statement of when to use this tool versus list_firewall_policies, get_policy_stats, or the mutation siblings, and no prerequisites or exclusions are given. The agent must infer that a single policy is fetched by ID.

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

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

With no annotations the description carries the full behavioral burden, and it does disclose a meaningful trait: images and upgrade paths are sourced from FortiGuard, so an eval license returns none, with a psirt URL for manual lookup. It does not state read-only nature, permissions, or rate limits, so disclosure is partial rather than rich.

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?

Two dense sentences, both earning their place: the first front-loads the returned data, the second carries the eval-license caveat and the manual-check pointer. No filler or restatement of the name.

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?

There is no output schema, but the description itself enumerates the returned fields and the key edge case (eval license producing empty image lists), which is enough for an agent to call and interpret it. It could go further on read-only/authorization context, but for a one-parameter status readout it is close to complete.

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% for the single vdom parameter with its default documented, so the schema does the heavy lifting and baseline 3 applies. The description adds no syntax or format detail about vdom beyond what the schema already provides.

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 specific verb-and-resource readout, enumerating exactly what is returned: running version/build/maturity/release notes, newer FortiGuard images, supported upgrade path, and auto-upgrade settings. Purpose is unambiguous, though it never distinguishes itself from close siblings like get_fortiguard_status or get_system_status.

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?

Usage is implied (check the firmware status) but there is no explicit when-to-use vs. when-not, and no routing to alternative tools such as get_fortiguard_status. The one conditional hint — evaluation licenses list no images — is genuinely useful but is a data caveat rather than selection guidance.

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

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

With no annotations, the description carries the burden and does well: it discloses that it synthesizes findings (failing servers, stale signatures, disabled schedule) and explains an edge case (free eval license reports FortiGuard unavailable by design). It does not state auth requirements or whether live queries make the call slow, which are the remaining gaps.

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 every clause corresponds to real output content, so little is wasted despite the dense, semicolon-heavy sentence. It is on the long side but earns its length through specificity.

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?

There is no output schema, so the description must explain returns, and it does comprehensively — enumerating the fields reported and the derived findings. Nothing an agent needs to interpret the result is missing.

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?

Only one parameter (vdom) with 100% schema description coverage, so the schema fully documents it. The description adds no extra meaning about the vdom argument, making the baseline 3 correct.

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 states precisely what the tool reports: FortiGuard connection state, per-server reachability and packet loss, update schedule, licensed services, and signature database age. It reads as a status/read tool, implicitly distinct from the mutating sibling update_fortiguard. It never explicitly names a sibling to differentiate, so 4 rather than 5.

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 call this versus update_fortiguard, get_license_status, or get_firmware_status, all of which live nearby. The description covers content, not invocation context, so the agent must infer usage.

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

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

With no annotations, the description carries the full burden, and it does real work: it discloses the anomaly-flagging behavior (out-of-sync members, unencrypted/unauthenticated heartbeats, single heartbeat interface, no session pickup), which tells the agent what negative results mean. It does not state that the call is strictly read-only, nor any auth/rate-limit constraints, keeping it short of a 5.

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?

Two dense sentences: the first enumerates returned fields, the second the warning flags. It is front-loaded ('High availability: the mode...') and free of filler, though the first sentence is a very long list that could be structured more scannably.

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?

No output schema exists, so the description must describe returns — and it does so thoroughly, including diagnostic flags an agent would otherwise misinterpret. The only real gap is absent usage/prerequisite guidance for a status tool.

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 100% — the single vdom parameter is fully documented in the schema with its default and meaning. The description adds nothing about the parameter, so the baseline 3 applies.

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 names the specific resource (HA cluster state) and enumerates exactly what it reports: mode, group, heartbeat/monitored interfaces, member roles/priorities/uptime, and sync state. This clearly separates it from siblings like get_system_status or get_interface_status, though it never explicitly contrasts itself with them.

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 text is entirely about what the tool returns; it gives no when-to-use framing, no prerequisites, and no alternative tools for related diagnostics (e.g., get_system_status). Usage is only implied by the tool name and content.

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

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

No annotations are provided, so the description carries the full disclosure burden. 'Get' implies read-only, but it says nothing about authentication needs, required permissions, pagination, or what 'full configuration' actually includes.

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?

A single tight sentence with the key scope qualifier ('one interface's full configuration') front-loaded. No wasted words, though there is little content to structure.

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 config-retrieval tool with no output schema and no annotations, the description is too thin to tell the agent what a caller receives or how it differs from get_interface_status. More detail on the returned configuration would be needed here.

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% with only two parameters, so the schema already documents 'name' (with the port1 example) and 'vdom' (with a default). The description adds nothing beyond that baseline.

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?

States a specific verb ('Get') and resource ('one interface's full configuration'), making it clear this is a single-object read rather than a list. It does not explicitly distinguish itself from the close sibling get_interface_status, so it falls short of the top tier.

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?

No guidance on when to choose this over list_interfaces (enumerate all) or get_interface_status (status vs. full config), nor any prerequisite or VDOM context advice. The agent must infer the selection criteria from the sibling names alone.

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

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

No annotations are provided, so the description carries the full burden. It signals a non-persistent, live read of current state and enumerates the values returned, which is useful behavioral context, but it says nothing about required permissions, whether it is strictly read-only, or behavior on an invalid interface.

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?

A single tight sentence with the key noun ('Live interface state') front-loaded and no filler. It is efficient, though its brevity leaves the usage gap that other dimensions penalize.

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 usefully names the returned fields, partially compensating for the missing return documentation. But it omits usage context relative to sibling interface tools and any behavioral/permission detail, leaving meaningful gaps for a 2-parameter status tool.

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 the schema already documents both vdom and interface, including the default note for vdom. The description adds no parameter-level meaning beyond what the schema states, so the baseline 3 is appropriate.

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?

States a specific resource (interface state) and enumerates the fields returned (link, speed, IP, traffic counters), so the agent knows exactly what it gets. However it does not distinguish itself from siblings like get_interface or list_interfaces, which an agent could easily confuse with it.

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 explicit when-to-use guidance, no statement of prerequisites, and no reference to the sibling tools (get_interface, list_interfaces) that an agent must choose between. The word 'Live' faintly implies real-time status versus config, but this is inference, not guidance.

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

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

With no annotations, the description carries the full behavioral burden, and it does disclose the substance of the operation: the license mode, FortiGuard reachability, per-service licensed/not-licensed/expiring status, a 30-day expiry window, and database versions and ages. It stops short of stating read-only/side-effect-free behavior or any permission requirements, but for a read tool the disclosed output scope is strong.

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?

One dense, front-loaded sentence covers the purpose and contents, followed by a short usage note. The FortiGuard service enumeration is long but each item is informative rather than padding, and the key point (license entitlements) leads.

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 and no annotations, the description must describe the return payload, and it does so thoroughly enough for an agent to know what it will receive. Minor gaps remain: no mention of the vdom parameter's effect or the fact that the call is a safe read.

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% and the single vdom parameter already documents itself with a default. The description adds nothing about vdom scope or defaults, so the baseline 3 for schema-covered parameters applies.

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 names a specific verb+resource pair (get license/feature entitlements) and enumerates exactly what is reported: VM vs hardware licensing, FortiGuard reachability, per-service license state, and signature DB version/age. It is clearly distinct from a generic status read, though it never explicitly contrasts itself with siblings like get_license_status or get_license_limits.

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 closing sentence ('Tools that need a FortiGuard service check this and say so when it's missing') gives useful context about how the tool is consumed, but it describes its role in a workflow rather than telling the agent when to call it versus get_license_status or get_fortiguard_status. No explicit when/when-not or alternative routing is provided.

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

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

With no annotations, the description carries the full burden. It implies a read-only query and adds genuinely useful domain context (the free eval license ceilings of 1 vCPU, 2 GB RAM, 3 interfaces/policies/routes), but it says nothing about required permissions, whether counters are live or cached, or what the response contains.

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?

Two sentences, front-loaded with the core purpose, followed by actionable context about the eval limits. The second sentence is long but earns its place by explaining what counts against each limit; nothing is redundant filler.

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 one-optional-parameter read tool with no output schema, the description gives a reasonable sense of what is returned ('lists what counts against each'), but it does not describe the shape of the output or how the limits are represented, leaving a gap that the absent output schema cannot fill.

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?

The single vdom parameter is fully documented in the schema (100% coverage), so the schema does the heavy lifting. The description adds no meaning about vdom scoping or defaults beyond what the schema provides, making the 3 baseline correct.

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 names a specific verb+resource ('how much of the license's object limits is used') and enumerates the concrete limits tracked. It is clear on its own, but it does not differentiate itself from siblings like get_license_status or get_resource_usage, which an agent may confuse it with.

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?

Usage is only implied through the phrase 'so you can plan before hitting one', which suggests checking headroom ahead of provisioning. There is no explicit when-to-use, when-not-to-use, or comparison against get_license_status / get_resource_usage, so the routing decision is left to inference.

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

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

With no annotations, the description carries the full burden and does well: it discloses the default return scope, what all=true expands to, and the notable side effect that an unlicensed FortiGate-VM reports vm.status=vm_invalid and refuses most other API calls with 401. It does not cover auth requirements or pagination, but the behavioral disclosure is substantive.

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 dense, front-loaded sentences with no filler. The default-scope behavior and the failure mode are each stated once and earn their place, though the 401 note is a minor tangent to the tool's core purpose.

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 and no annotations, the description does most of the heavy lifting: it names the returned sections (VM license, FortiCare, FortiGuard) and a key return field (vm.status=vm_invalid). This is nearly complete for a simple two-parameter read tool, though it omits the full response shape.

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 both parameters are already documented, establishing a baseline of 3. The description's statement about default vs all=true return scope slightly enriches the meaning of `all`, but adds little beyond the schema text ('Return every entitlement (default false)').

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?

States a specific verb+resource: retrieving license and FortiGuard contract status. It is clearly distinct from the sibling get_license_limits (status vs limits), though it does not name the sibling explicitly. The purpose is unambiguous without opening the schema.

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?

Gives clear context on when to set all=true ('set all=true for every entitlement') versus the default subset, and explains a diagnostic use case (unlicensed VM refusing calls with 401). It lacks an explicit routing statement to alternatives like get_license_limits, but the usage context is strong.

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

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

With no annotations, the description carries the full burden, and it does disclose two non-obvious behaviors: results are ordered newest-first, and on FortiGate-VMs without a log disk, logs live only in memory and are lost on reboot. It does not cover pagination semantics or required permissions, but the retention caveat is genuinely useful operational context.

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?

Front-loaded with the core action and ordering, then a compact catalog of log types, then the retention caveat. The type enumeration is long but each entry carries differentiating information, so little is wasted.

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?

All 8 parameters are documented in the schema and there is no output schema to explain, so the description only needs to add orientation. It supplies result ordering, log-type meaning, and a deployment caveat; the main gap is paging behavior (start/rows) and any authorization requirement.

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 100%, so the baseline is 3, and the description earns a bump by explaining what several log_type values actually contain ('traffic/forward' = sessions through policies with app identification; 'app-ctrl' = per-connection app and HTTPS hostname under certificate inspection). This adds meaning beyond the bare enum list in the schema, and the memory/disk remark contextualizes the 'source' parameter.

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?

States a specific verb and resource ('Read FortiGate logs') plus the ordering convention ('newest first'), which tells an agent exactly what comes back. It never names a sibling (e.g. get_log_targets, which configures destinations rather than reading), so the differentiation from the many list_/get_ siblings is left implicit.

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 explains which log types are 'useful' and what each contains, which implicitly guides log_type selection, but it never states when to reach for get_logs versus related tools like get_log_targets, list_sessions, or audit_admin_access. No exclusions or prerequisites are given.

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

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

With no annotations, the description carries the full burden, and it does add substantive behavioral context: it surfaces risk flags such as memory-only logs lost on reboot, cleartext UDP syslog, and FortiAnalyzer without certificate verification. However, it never states that this is a read-only operation, nor does it mention permissions or rate limits.

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?

A single dense sentence that front-loads the primary answer ('where logs go') before listing destinations and risk flags. No filler, though the warning clauses make it slightly long for one sentence.

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 and no annotations, the description must describe the return content, and it does so reasonably well — destination types, transports, encryption, and notable warnings. It is nearly complete, missing only read-only/auth framing.

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% and the single optional 'vdom' parameter is fully documented in the schema, so the description provides no additional parameter meaning. Baseline 3 applies when the schema does the heavy lifting.

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 names the resource ('where logs go') and enumerates the destinations returned (syslog servers, FortiAnalyzer, FortiGuard Cloud, local disk/memory) with transport and encryption context. This clearly distinguishes it from siblings like get_logs and set_syslog_target, though it never names those alternatives.

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 tool versus alternatives such as get_logs (retrieve log data) or set_syslog_target (configure destinations). Usage is only implied by the resource name.

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

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. It usefully discloses that this is a read-only path and that POST monitor endpoints cause device actions (reboots, disconnects, updates), which is genuinely valuable risk context. However, it says nothing about authentication requirements, rate limits, pagination, or error behavior for the GET endpoints it does allow.

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?

Two sentences, front-loaded with the core capability before the constraint. Every clause earns its place: the examples establish scope, and the reboots/disconnects/updates parenthetical justifies the POST exclusion.

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?

No output schema exists, so the description could say more about what live-state data comes back, but for a generic endpoint proxy that is inherently endpoint-specific. Parameters are schema-covered and the GET/POST boundary is covered, leaving only return-format and multi-request behavior unaddressed.

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 vdom, params, and endpoint are already documented in the schema. The description only reinforces endpoint examples (system/ha-peer, router/ipv4) already implied by the schema's examples, adding little syntax or format detail beyond it. Baseline 3 is appropriate.

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?

States a specific verb (Read) and a specific resource (any monitor / live-state endpoint) and names its scope with concrete examples (system/ha-peer, router/ipv4, vpn/ipsec, user/firewall). It also distinguishes itself from siblings by routing POST monitor endpoints to the dedicated tools or fortigate_api.

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?

Explicitly states when NOT to use it: endpoints FortiOS only serves with POST belong to dedicated tools or fortigate_api. That is a clear usage boundary. It doesn't spell out when to prefer a dedicated read tool (e.g. get_system_status) over this generic one, which keeps it from a 5.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the returned metrics but says nothing about whether this is a read-only operation, permission requirements, whether counters are cumulative/resettable, or how stale last-used data might be.

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?

A single front-loaded sentence listing the metric set with zero filler. It is efficient, though terse enough that it under-specifies rather than over-explains.

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?

There is no output schema, so the description does useful work by naming the returned metrics. However, with no annotations and no usage or caveat context for a stats tool, it is only minimally complete for an agent that needs to know when and why to call it.

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%: the vdom default (FORTIGATE_VDOM, usually root) and the optional policyid filter are fully documented in the schema. The description adds no parameter-level information beyond that, so the baseline 3 applies.

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 names the resource (policy) and enumerates the returned statistics (hit counts, bytes, packets, last-used time), so an agent knows this is a per-policy counters/metrics reader distinct from get_firewall_policy or list_firewall_policies. It lacks an explicit verb like 'retrieve', but the resource and payload are clear.

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?

No statement of when to use this versus alternatives such as get_top_traffic, get_firewall_policy, or get_system_status. It does not mention the vdom scoping default or the one-policy filter as a usage consideration, leaving the agent to infer everything from the schema.

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

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

With no annotations, the description carries the full behavioral burden. It implies a read-only snapshot via 'Current' but says nothing about permissions, whether the call is expensive, or whether values are instantaneous vs averaged. For a monitoring tool with zero annotation coverage, this is thin.

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?

A single short sentence with no filler, and the metric list is front-loaded. It is a fragment without an explicit verb, which costs a little clarity but wastes no space.

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 simple read tool with one optional, fully documented parameter and no output schema, the description is roughly sufficient to invoke correctly. It is still ambiguous about what 'session usage' means relative to the sibling list_sessions, and gives no sense of the returned shape.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.