start_task

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

Discloses key behaviors: only works if issue assigned to user, returns error without changes otherwise, and states it does not touch git. With no annotations, description carries full burden and covers important side effects.

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?

Concise Spanish description, front-loads the main action, no wasted sentences. Every sentence serves a purpose: action, parameter explanation, prerequisite, side-effect note.

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?

Complete for a Jira transition tool with moderate complexity. Covers default status, custom transitions, assignment requirement, and clarifies no git involvement. No output schema, but behavior is well explained.

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?

Specifies 'issue_key' is required and explains 'status': default to configured in-progress, or use a custom transition name. Adds meaning beyond schema (which has 0% coverage), though could mention expected format of 'issue_key'.

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 transitions an issue in Jira, specifying the default action (move to 'in progress') and the optional custom status. It distinguishes from siblings: 'create_task' (create) and 'list_my_tasks' (list).

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?

Provides clear context: use when starting work on an issue, with guidance on the 'status' parameter for pre-development steps. Implicitly excludes when not assigned (returns error) and mentions no git interaction, but no explicit when-not-to-use or alternatives.

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