polaris_fitness_functions

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

With no annotations, the description carries the whole burden and largely succeeds: it discloses that versions are immutable after activation, that If-Match can be passed explicitly via `revision` or defaulted to the current one, that retire is terminal while history stays queryable, and that validation has no side effects. It omits permission/auth requirements, error behavior, and pagination semantics for limit/cursor/all_pages.

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?

Front-loaded one-line purpose followed by a scannable action/required-parameter list and then a nested spec for the one complex object argument. Despite its length, nearly every line conveys routing or schema information the agent cannot get elsewhere, so it is dense rather than padded.

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?

For a ten-parameter, eight-action tool with no annotations and no output schema, the description covers the action surface, concurrency model, lifecycle transitions, and the full definition contract. It stops short of describing return shapes or pagination limits, which leaves some inference required for list/get responses.

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 0%, yet the description documents almost every parameter in context: squad_id, fitness_function_id, version, revision (If-Match), reason, and the limit/cursor/all_pages pagination set per action. The `definition` param — otherwise an opaque object — is spelled out in detail including required fields, camelCase key convention, criterion key pattern, enum values for comparisons and reduction/seriesPolicy, and the warning-vs-failure threshold constraint.

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 opening sentence names a specific resource ('fitness functions: versioned definitions of intent, scope, criteria, acquisition, freshness, and enforcement') and the rest of the description enumerates all eight actions with their required parameters. An agent can distinguish this definition-management tool from siblings like polaris_evaluations or polaris_fitness_targets without opening any schema.

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 gives clear per-action context: validate_version 're-runs validation without side effects', activate_version makes evaluations use the definition, retire is terminal, and update_draft_version only touches still-DRAFT versions. It does not, however, point the agent to sibling tools for adjacent tasks (e.g., polaris_fitness_function_templates for template-based creation), so the routing guidance is strong but not complete.

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