aggregate-spans

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

No annotations are provided, so the description must carry the full behavioral transparency burden. It states the tool computes statistics and lists supported aggregations, implying a read-only operation. However, it does not disclose any additional behavioral traits such as rate limits, pagination, error handling, or what happens with missing data. This is adequate for a simple aggregation tool but lacks depth.

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 extremely concise: three sentences that immediately state the purpose, provide examples, and list supported aggregations. It is front-loaded with the most important information and contains no unnecessary words. Each sentence earns its place.

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 has three parameters with nested objects and no output schema, the description provides reasonable context: it explains that the tool computes statistics, lists supported aggregations, and contrasts with search-spans for details. It does not explain the output format (e.g., JSON object with aggregated data) or mention any time series behavior, but for an aggregation tool, the description is sufficiently complete for an agent to understand its purpose and basic usage.

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 0% description coverage, but the tool description compensates by listing the supported aggregation types (count, avg, sum, min, max, percentiles) and mentioning group-by fields like 'service' and 'resource_name'. This adds context beyond the schema's minimal field descriptions. However, it does not fully explain all parameter nuances, such as the 'filter' object's structure or the 'type' field in compute. It is adequate but not excellent.

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 computes statistics on APM spans, with specific use case examples like 'p99 latency by service'. It distinguishes itself from the sibling tool 'search-spans' by specifying that this tool is for aggregation, while search-spans is for seeing details. The verb 'compute statistics' and resource 'APM spans' are specific and unambiguous.

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 tells when to use this tool (for aggregated metrics like p99 latency, error rate, request count) and when to use the alternative (search-spans for detailed span data). It lists supported aggregation types, giving the agent clear instructions on what operations are possible.

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