Create sprint

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

Annotations already mark this as a write operation with idempotentHint=false, but the description adds valuable behavioral context: the sprint is not started, startDate/endDate only plan the window, and duplicate sprints are possible on repeated calls. This goes meaningfully beyond the structured annotations.

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 compact, front-loaded with the core action, and every sentence earns its place: purpose, lifecycle caveat, date semantics, and duplicate-risk warning. No filler or repetition of schema content.

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 no output schema, the description appropriately notes the id return value. It also covers the main risks an agent must handle: non-idempotency, future state, and the relationship to jira_start_sprint. With 100% parameter schema coverage, nothing critical is left to guesswork.

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 coverage is 100%, so the parameters are already well documented individually. The description adds relationship-level meaning by clarifying that startDate and endDate are only planning values, not the actual start, and that the start requires both. This is genuinely useful semantics beyond the schema fields.

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?

States a precise verb and resource: 'Creates a sprint on a Scrum board and returns its id.' It also differentiates from jira_start_sprint and jira_list_sprints, so an agent can distinguish this creation action from lifecycle and listing siblings without opening schemas.

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?

Gives explicit usage context: the sprint is created in the 'future' state and not started; jira_start_sprint is the named alternative for actually starting it. It also warns that repeated calls create duplicate sprints and tells the agent to check jira_list_sprints first, which is concrete when-to-use guidance.

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