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

Annotations already indicate readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds valuable behavioral context: labels not existing are created on the project (side effect), description must be in AgileHero Markup (format constraint), estimation is Fibonacci complexity not time, and epics/assignees must already exist (prerequisites). No contradictions with annotations; this enriches the agent's understanding.

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 front-loaded with the essential purpose and required parameters, then systematically covers optional behaviors and constraints. Every sentence adds unique value—there is no fluff or repetition of schema details. It is longer than average but each clause earns its place, making it dense yet efficient.

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 tool's complexity (15 parameters, nested objects for checklists/attachments/relations, and multiple enums), the description covers the critical aspects: required fields, default behaviors (backlog, end of queue), format requirements (AHM), prerequisites, side effects (label creation), and the ability to supply related items in one call. There is no output schema, so return details are not required. The description is comprehensive for an agent to call this 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?

Schema description coverage is 80%, but the description adds significant meaning beyond the schema: it clarifies that only project_id and title are required, explains the effect of omitting list_id and position, defines estimation as Fibonacci not time, notes that labels are auto-created, and points to list_epics and list_project_users for validation. This goes well beyond a simple mapping of parameter names.

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 the tool's action: 'Create a card on a project's kanban board.' It specifies the resource (card) and the context (project's kanban board), and differentiates from siblings like update_card, move_card, and delete_card by focusing on creation. The statement 'Only project_id and title are required' further clarifies the core scope.

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 explicit usage guidance: omitting list_id places the card in the backlog, omitting position joins the end of the queue, and references move_card for the position contract. It also instructs to read get_ahm_spec before using description, and clarifies prerequisites for epic_id and assigned_to via list_epics and list_project_users. This goes beyond vague when-to-use and offers actionable conditions.

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