knowbe4_phishing_security_tests_list

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

No annotations are provided, so the description carries the burden. It discloses the returned data types (status, phish-prone percentage, recipient counts), which is useful. However, it does not disclose pagination behavior (default page/per_page), data volume expectations, or whether any subset goes 'all' (the 'all' may effectively be limited by pagination). It's a read/list operation with clear return intent, though somewhat thin on behavioral detail.

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?

Single, efficient sentence that states the resource, scope, and return fields. Zero filler words. Front-loaded with the core action and resource.

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 list/read tool with fully documented parameters, the description is reasonably complete. It names the key return fields and scope. Minor gaps: no mention of pagination defaults being in the schema (covered there), no note about result ordering, and no sibling-contrast guidance. But no output schema is present, so some return-context clarification is useful—which it provides. Adequate for a filter-free listing 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% (both page and per_page fully documented in schema). The description doesn't add per-parameter detail, but with full schema coverage the baseline is 3. The description's 'all' phrasing connects to the scrolling behavior of page/per_page, adding slight context over the raw schema. Minor extra value over 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?

Clear verb+resource: 'List all Phishing Security Tests (PSTs) across all campaigns.' It specifies scope (all campaigns), distinguishes from siblings like knowbe4_phishing_security_test_get (single) and knowbe4_phishing_campaign_tests (per-campaign).

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 states a broad 'across all campaigns' scope, which implies these are the tests aggregated across campaigns, helpful when you want the full PST picture rather than per-campaign. However, it does not explicitly contrast with sibling tools like knowbe4_phishing_campaign_tests (tests for a specific campaign) or when to choose one over the other. Usage context is implied but not made explicit with alternatives.

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