knowbe4_reporting_phishing_summary

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It appropriately indicates this is a read/aggregation operation (fetch + compute statistics). However, it doesn't disclose that pagination params could lead to partial aggregation across pages if many PSTs exist, nor does it describe the output format. The behavior described is consistent and non-misleading, but lacks depth on edge cases.

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, zero waste. The first sentence states purpose and deliverables; the second explains the implementation approach. Every clause earns its place with no 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 summary/aggregation tool with no output schema and only 2 fully-documented parameters, this description is reasonably complete. It clearly names the computed metrics and the source data. A minor gap: it doesn't warn about pagination affecting aggregate completeness when PST count exceeds per_page, which is a genuine edge case for a tool explicitly labeled as computing 'all' summary statistics.

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 (page, per_page) are fully documented in the schema. The description doesn't add parameter-level semantics beyond 'Fetches all PSTs', but with full schema coverage the baseline of 3 is appropriate. The description implies pagination matters for aggregation completeness, but doesn't explicitly explain that per_page lower than total PSTs could skew summary statistics.

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 uses a specific verb ('Get a summary') with a clear resource ('all phishing security tests') and explicitly lists the outputs (phish-prone percentage, total tests, aggregate click/open/report rates). It distinguishes itself from siblings: while knowbe4_phishing_security_tests_list and knowbe4_phishing_security_test_get retrieve individual test data, this tool aggregates across all PSTs into summary statistics. Sibling names like 'list' and 'get' are clearly differentiated from 'summary'.

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 clearly states the tool fetches all PSTs and computes summary statistics, giving an agent enough context to know this is for aggregate reporting rather than per-test retrieval. However, it doesn't explicitly name alternative tools like knowbe4_phishing_security_tests_list for per-test detail, or state when NOT to use it, so it falls just short of an explicit when/when-not contrast.

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