pm_wifi_roaming_analysis

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

No annotations are provided, so the description must convey behavioral traits. However, it only lists the types of events included in the timeline (reassoc, neighbor reports, etc.) without disclosing whether the tool is read-only, modifies state, requires special permissions, or has limitations. The description does not compensate for the lack of annotations.

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

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

The description is extremely concise at 13 words, which earns its place but sacrifices necessary detail. It is front-loaded with the core purpose, but for a tool with multiple parameters and no annotations, conciseness becomes under-specification. A balance is required; this is too minimal.

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?

Given the tool has 3 parameters (2 required) and no parameter descriptions or annotations, the description is incomplete. It does not mention the output schema or explain the return value, nor does it provide context on when to set sample_limit. For a moderately complex tool like roaming timeline analysis, more context is needed.

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

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% (no parameter descriptions). The description does not explain any of the three parameters: file_path, wlan_addr, sample_limit. The user has no clue what values to provide for wlan_addr or sample_limit. Even though an output schema exists, the description adds zero value to understanding parameters.

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?

Description clearly defines a specific verb+resource: it provides a timeline of 802.11k/v roaming events including reassoc, neighbor reports, BSS transition, and deauth. This distinguishes it from siblings like pm_wifi_client_analysis (which likely focuses on client details) and pm_wifi_quick_scan (a broader scan). The specification of events makes the purpose concrete and 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 guidance on when to use this tool versus alternatives. The tool name and description imply it's for WiFi roaming analysis, but there is no mention of prerequisites, context, or exclusion criteria. Sibling tools like pm_wifi_client_analysis or pm_troubleshoot_quick_scan could overlap; the description fails to clarify when each is appropriate.

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