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

Adds high-value mutation semantics not present in annotations: changing projectId wipes the milestone unless milestoneId is sent in the same call, changing productId clears its milestone, and permission nuance (product-only writers may change productMilestoneId but not content). Also explains workspaceId resolution on create vs update. It is consistent with destructiveHint=true and readOnlyHint=false, so no contradiction, though it never says what the create response body looks like beyond naming the workspace.

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 create/update split is front-loaded and the caveats are attached to the fields they affect, so a reader can stop early. It is dense and long for a description, with some repetition around milestone/product milestone clearing, but nearly every sentence carries a rule an agent cannot infer elsewhere.

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?

For a 23-parameter, zero-required, no-output-schema mutation tool this is a solid briefing covering the dangerous cross-field interactions and ID resolution. It falls short of complete because six parameters are never mentioned and the expected create-time payload/response shape is only gestured at ('la respuesta dice en qué workspace quedó').

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 only 4%, so the description must carry the load and largely does: description, agentContext, definitionOfDone, verifyCommand, assigneeId, projectId/milestoneId relationship, dueDate (epoch ms, null clears), parentId, labelIds vs addLabelIds/removeLabelIds, agentReady, productId/productMilestoneId and workspaceId all get meaning. Gaps remain for title, teamId, stateId, estimate, priority and customFields, which get no explanation at all despite being untyped in the schema.

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?

Opening sentence states a specific verb+resource ('Crea una issue... o actualiza una existente si se pasa id') and the discriminator between the two modes is the presence of `id`. It also marks the atomic TEAM-N numbering, distinguishing it from a plain create from the siblings.

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?

Explicit routing: pass `id` to update, omit it to create; use list_workflow_states/list_labels/list_milestones/list_members/list_custom_fields to resolve IDs; create milestones with save_milestone; agentReady feeds the next_ready_issue queue without changing state. Exclusions and prerequisites are stated rather than inferred.

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