get_trends

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

Annotations already convey read-only and non-destructive behavior. The description adds useful behavioral context beyond annotations: windowSatisfied can be false when not enough history exists, and comparisons then run over less data than requested. It also discloses that segmentBoundaries lists logged point events in the span.

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 compact and front-loaded, opening with the main action and expected outputs. It adds technical details about windowSatisfied and segmentBoundaries without excessive filler. It is slightly dense but every sentence contributes semantic value.

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?

There is no output schema, so the description carries the burden of explaining return data, which it does well: change, percent change, direction, daysAvailable, windowSatisfied, and segmentBoundaries. It does not fully address possible error/precondition cases or clarify metric validity, but for a read-only idempotent trend tool the essentials are present.

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 67%, with window and excludeTravelDays already documented in the input schema. The description adds a general 'N-day window' concept but does not explain the required metric parameter or add meaning for excludeTravelDays beyond the schema. It compensates only partially for the undocumented metric parameter.

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 it compares the most recent N-day window against the prior N days for a metric and returns change, percent change, and direction. This distinguishes it from more generic query tools, but it does not explicitly contrast it with the closely named sibling compare_periods, so it stops short of full sibling differentiation.

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 usage context is implied rather than stated: an agent can see it is meant for window-over-window trend comparisons. However, there is no explicit guidance about when not to use it, when to prefer compare_periods or get_health_metrics instead, or what prerequisite conditions apply.

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