create_ticket

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

Annotations indicate write-operation (readOnlyHint:false) and external system impact (openWorldHint:true). The description adds valuable context: it confirms creation of 'REAL' external tickets, implies duplicate detection exists (via the 'force' parameter mentioning 'Skip duplicate check'), and describes post-commit behavior (returns URL, ID, confirmation). Minor gap: doesn't mention authentication requirements or failure modes.

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?

While helpfully structured with capitalized headers ('COMMIT', 'USE', 'IMPORTANT'), the description is overly verbose. The post-success confirmation instructions ('confirm with: The ticket URL...') could belong in system prompts rather than tool description. Some redundancy exists ('This makes it real' vs 'creates a REAL ticket').

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 the complexity (5 parameters, nested objects, external system interactions, no output schema), the description adequately covers critical gaps. It explains the workflow position, parameter precedence (draftId vs idea), and expected return behavior (URL, ID). Missing: explicit error handling or authentication prerequisites, though `check_auth` exists as a sibling tool.

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?

With 60% schema coverage, the description adds crucial semantic information about the draftId/idea relationship: 'If a normalize_idea was just called, use the draftId... If no draftId is available, pass the full idea object.' This workflow dependency isn't fully captured in the raw schema and helps the agent choose correctly between mutually exclusive approaches.

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 'COMMIT an idea to GitHub, Jira, or Linear' providing a specific verb and target resource. It clearly distinguishes this from siblings like `normalize_idea` (preparatory step) and `create_idea` (internal creation) by stating this is 'the final step in the IdeaLift flow' and creates a 'REAL ticket' in external systems.

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?

Excellent explicit guidance including: trigger phrases ('Commit it', 'ship it', etc.), workflow context ('final step in the IdeaLift flow: Capture → Normalize → COMMIT'), and prerequisite handling ('If a normalize_idea was just called, use the draftId'). It explicitly names the alternative parameter source and instructs 'NEVER ask the user to re-provide content that was just normalized.'

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