get_fortiview_top

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 the important behaviors: data comes from live session statistics (not stored logs) and results are 'one line per entry with sessions, bytes and bandwidth'. It states default and maximum row counts and which parameters are optional, though it does not note whether the call is read-only-safe or costly on the device.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose line is front-loaded and the parameter/return lists are scannable. Some content duplicates the schema verbatim, but the structure is efficient and nothing is buried.

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 the description compensates by describing the return shape (sessions, bytes, bandwidth per row). All six parameters are accounted for, including optionality; the main gap is guidance on choosing this tool over sibling monitoring 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 every parameter and both enums. The description restates the same defaults and enum values (source default, bytes default, count max 200) without adding new semantics such as value formats or interactions between report_by and sort_by, 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 (get) plus a named resource (FortiView top talkers) and pins the underlying data source (monitor/fortiview/statistics), so an agent knows it is a live analytics view rather than a raw session or log listing. It does not explicitly name sibling alternatives such as list_active_sessions or query_traffic_log, which is the only thing keeping it from 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?

Usage is only implied: the mention of 'live session statistics' hints this is for current top-talker analysis, but the description never says when to prefer it over query_traffic_log (historical) or list_active_sessions (per-session detail). No prerequisites or exclusions are given.

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