tempo_create_plan

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description discloses a significant behavioral trait: the tool requires user confirmation, and in non-elicitation environments the first call returns a preview and confirmToken rather than executing. This is exactly the kind of behavioral context an agent needs to avoid prematurely invoking a destructive operation.

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?

Two sentences deliver the core purpose, the confirmation behavior, the fallback mechanism, and the confirmToken repeat-call rule. Every clause earns its place and the most important behavioral caveat is front-loaded.

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?

With 15 parameters, 100% schema coverage, and no output schema, the description covers the essential operational flow well: confirmation, preview, and confirmToken handling. It does not describe the success response shape, but the confirmation behavior is the critical missing piece that the description supplies, making it sufficiently complete for an agent to invoke the tool correctly.

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 schema already documents all 15 parameters with 100% coverage, so the baseline is 3. The description adds a little semantic framing by tying 'user or generic resource' to assignee types and 'issue or project' to plan item types, but it does not add detail beyond what the schema already provides for individual parameters.

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 states a specific verb ('Create'), a specific resource ('a new Tempo plan'), and the planning context ('resource allocation for a user or generic resource against an issue or project'). It clearly distinguishes this from worklog creation and from tempo_update_plan by framing it as creating a plan rather than modifying one.

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 clear context for when this tool is used: when a new plan needs to be created. It also gives crucial operational guidance about the confirmation flow, including the two-step fallback with confirmToken. It does not explicitly name alternatives like tempo_update_plan, but the 'Create a new' framing makes the usage context unambiguous.

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