apply_track

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

The description goes well beyond annotations by warning that the operation is NOT IDEMPOTENT, explaining that duplicate applications create duplicate instances/tasks, and detailing how startDate drives dueOn computation. It also discloses a subtle source of noise (auto-applied tracks from board rules). Annotations only indicate it is not read-only and not destructive, so the description carries and fully satisfies the transparency burden.

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?

Every sentence earns its place: main action, side effects, date calculation, template discovery, idempotency warning, and pre-check guidance. The most critical behavioral warning (non-idempotency) is bolded and placed prominently.

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?

The description covers purpose, side effects, date logic, idempotency, discovery, and pre-check workflow. The only minor gap is that it does not describe the return value, and there is no output schema to fill that void; for a create-style tool this is a small omission.

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 descriptions already cover entity, startDate, and trackDefinitionId. The tool description adds meaningful semantics by explaining how startDate defaults to today and how it combines with each task's daysAfter offset, and that trackDefinitionId auto-creates task definitions. entityId lacks a schema description and is not elaborated in the tool description, but its purpose is self-evident.

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 opens with a specific verb+resource: 'Apply a track definition to an opportunity or project.' It goes on to clarify the outcome (creates a track instance and auto-creates tasks), which clearly differentiates it from sibling operations like update_track or remove_track and positions it relative to list_track_definitions.

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?

It explicitly tells the agent to use list_track_definitions to discover templates and to call list_entity_tracks first if single application is desired. The added caveat about board-stage auto-applied tracks provides nuanced guidance about when the pre-check may be unreliable.

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