qobrix_aggregate

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

With no annotations provided, the description carries the full burden and does well by disclosing server-side pagination with a 20,000-row cap and in-process computation. This goes beyond schema info. It does not mention what happens when the cap is exceeded or any side effects, but for a read-only aggregation tool these are relatively minor gaps.

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 front-loaded with the core function, followed by behavioral details and three illustrative examples. It is longer than a minimal description but every sentence contributes meaningful information, making it 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?

The description covers purpose, behavior, and parameters comprehensively with examples. However, since there is no output schema, it does not explicitly describe the return format (single aggregate vs. bucket list), nor does it address behavior when pagination cap of 20,000 rows is reached. These omissions leave some context incomplete for a complex aggregation 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%, and each parameter already has detailed semantics (op enum, search DSL, group_by, resolve, resource list). The tool description adds value through examples but does not introduce new parameter meaning beyond what the schema provides; it reinforces usage rather than expanding semantics.

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 function: aggregating a numeric field via sum/avg/min/max/count across records, with optional grouping and top-N buckets. It provides concrete examples (total 2026 closed-sale volume, agent leaderboard, average list price) that distinguish it from sibling list/search tools and specialized aggregation tools like qobrix_count or qobrix_top_values.

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 explicitly mentions 'which is how to get totals on Qobrix fields the API won't sort', giving a clear when-to-use signal. Multiple examples illustrate real use cases. However, it does not explicitly state when not to use it or name alternative tools for simpler counts or time-series aggregations, so it stops short of full exclusions.

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