get_docqa_stats

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

No annotations are provided, so the description must convey behavioral traits. It states the required assistant_id and implies a read-only operation (viewing stats), but it does not mention any side effects, authentication needs, rate limits, or potential limitations. The cryptic '[query]' suffix is unexplained and may confuse. Overall, minimal disclosure beyond the basic action.

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 concise—two short sentences plus the ambiguous '[query]' token. It is front-loaded with the core purpose. However, the stray '[query]' detracts from clarity and may be a leftover artifact, preventing a perfect score. Otherwise, it is well-structured and efficient.

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 that there is no output schema, the description should explain what statistics are returned. It only says 'estadisticas detalladas' (detailed statistics), which is vague. It does not list metrics, time frames, or how days affects the results. The prerequisite hints are helpful but incomplete for a tool that returns a non-trivial response. The unexplained '[query]' adds to the gaps.

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 provides 100% coverage with descriptions for both parameters: assistant_id (source hint from list_docqa_assistants) and days (default 30, range 1-365). The description reinforces the source hint for assistant_id but adds no new information that the schema doesn't already convey. With full schema coverage, the baseline is 3, and the description does not significantly elevate it.

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 states the tool's purpose: 'Ver estadisticas de asistente Doc Q&A' (view Doc Q&A assistant stats), specifying it provides detailed statistics for a documentation assistant. This distinguishes it from sibling tools like list_docqa_assistants (which lists assistants) and get_docqa_detail (which likely shows details rather than stats). The verb 'ver' and resource 'asistente Doc Q&A' are specific.

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 explicitly instructs to use list_docqa_assistants first to obtain the assistant_id, which is a clear prerequisite. It does not explicitly contrast with alternatives like get_docqa_logs or get_docqa_detail, but the prerequisite guidance helps the agent avoid errors and directs the user to a necessary preliminary step.

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