get_productivity_trend

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

No annotations are provided, so the description carries the full burden. It discloses that the tool 'Shows the daily productivity pulse with visual bars and calculates averages,' adding behavioral context about output format and calculations. However, it lacks details on permissions, rate limits, or data sources, which are important for a tool with no annotation coverage.

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 appropriately sized and front-loaded, starting with the core purpose, followed by parameter details and usage context. Each sentence adds value: the first defines the tool, the second explains the parameter, and the third describes output and utility. There's minimal waste, though it could be slightly more structured with bullet points.

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 one parameter, no annotations, but an output schema exists, the description is fairly complete. It covers the purpose, parameter semantics, and output behavior ('Shows... visual bars and calculates averages'). The output schema likely handles return values, so the description doesn't need to detail them. However, it could improve by addressing sibling tool differentiation or authentication needs.

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 description adds significant meaning beyond the input schema, which has 0% description coverage. It explains the 'days' parameter as 'Number of days to look back' with a default and max value, clarifying its purpose and constraints. Since there's only one parameter, this compensates well for the schema gap, though it could mention data types or validation rules.

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: 'Get productivity pulse trend for the last N days.' It specifies the verb ('Get') and resource ('productivity pulse trend') with a temporal scope ('last N days'). However, it doesn't explicitly differentiate from sibling tools like 'get_hourly_productivity' or 'get_today_summary' beyond mentioning 'daily' productivity pulse.

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 context by stating it's 'Useful for identifying patterns and trends over time,' which suggests when to use this tool. However, it doesn't provide explicit guidance on when to choose this over alternatives like 'get_today_summary' or 'get_hourly_productivity,' nor does it mention any exclusions or prerequisites.

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