wafle_agents_stats

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

Annotations already declare readOnlyHint and idempotentHint, so the description's read-only nature is covered. The description adds value by naming the specific metrics included in the stats, which is useful context beyond annotations. It does not disclose additional behavioral aspects like data freshness or pagination, but given the annotations, this is adequate.

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 a single sentence that is front-loaded with 'Aggregated stats for an agent' followed by a concise list of the metrics. Every word earns its place, with no redundancy or filler. It is optimally concise for the information conveyed.

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's moderate complexity, the description is largely complete: it covers the resource, the metrics returned, and (with annotations) the safety profile. The absence of an output schema is mitigated by listing the return metrics. It does not specify details like time range or aggregation period, which could be relevant, but these are not essential for a basic stats 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?

The input schema has 100% parameter description coverage for both 'slug' and 'agent_slug', so the schema fully explains the parameters. The description does not add any parameter-specific meaning beyond what is already in the schema, aligning with the baseline score of 3 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?

The description clearly identifies the resource as 'aggregated stats for an agent' and lists the specific metrics (total runs, success rate, total cost, top tool names), which distinguishes it from sibling tools like wafle_agents_get or wafle_agents_runs_list. However, it lacks an explicit action verb like 'Retrieve' or 'List', relying on the tool name to imply the operation, so it stops short of a perfect score.

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: use this tool when you need an agent's aggregate statistics. It does not explicitly state when to use it over alternatives such as wafle_agents_runs_list for raw runs or wafle_ai_usage for usage metrics, nor does it mention any exclusions. The guidance is present implicitly but not articulated.

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