Get Velocity

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses critical behavioral traits: it uses median and MAD instead of mean/stddev, detects and excludes bulk-close periods, reports story-point coverage, suppresses point velocity below 50% coverage, and always returns a range. This is substantial added value that an agent needs to interpret the output correctly.

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 four sentences long and front-loaded with the core purpose. Every sentence adds meaningful detail—method statistics, bulk-close handling, coverage suppression rationale, and the range output—without redundancy or fluff. 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 appropriately explains the key output behavior ('Always returns a commitment RANGE, never a single number') and covers the main edge cases (bulk-close exclusion, low-coverage suppression). It also clarifies the statistical approach, making the tool's behavior predictable and complete for an agent to select and invoke.

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 already documents all six parameters with descriptions (100% coverage), so the description doesn't need to compensate. The description adds a little context about 'recent periods' and 'bulk-close periods' that relates to the `periods` and `exclude_dates` parameters, but it does not go beyond what the schema provides in terms of parameter-specific meaning. Baseline 3 is appropriate.

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 'Compute delivery velocity for a person or project over recent periods,' using a specific verb and resource. It distinguishes itself from sibling Asana getters by focusing on a computed metric, and the detail about median/MAD and coverage thresholds sets it apart from simple data retrieval tools.

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 provides a clear context for use—'when you need delivery velocity'—and explains several methodological behaviors that imply when this tool is appropriate. However, it does not explicitly name alternatives or state when not to use it, such as comparing to asana_get_project_flow_metrics or task-count-only tools, so it falls short of a 5.

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