accelo_create_issue

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

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing beyond 'create' — no side effects (notifications, status defaults), no permission requirements, and no indication of what the against_type/against_id linkage does. For an unannotated mutation tool this is a notable gap.

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 core action and the required fields are marked, with no filler sentences. The raw 'Args:' block is functional though slightly mechanical, and required vs optional is only conveyed by the '(required)' tag on some entries.

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?

With no annotations and no output schema, the description covers the 13 parameters adequately but omits behavioral context: validation requirements, side effects, and what the call returns. It is minimally complete for a mutation tool but leaves an agent guessing about the write semantics.

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 0%, so the description's inline arg list is the only source of parameter meaning. It adds useful semantics beyond bare titles: against_type 'e.g. company, job', assignee as 'Staff ID to assign', date fields as 'unix timestamp', and 'fields: Additional fields to return'. A few IDs (type_id, class_id, status_id, priority_id) remain unexplained, but overall it compensates well for the schema gap.

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 a specific verb+resource: 'Create a new issue (ticket).' This cleanly distinguishes it from the update/delete/list/get issue siblings. It does not explicitly reference any sibling, but the create verb and parenthetical clarify the resource unambiguously.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The description never mentions prerequisites (e.g. that a valid type_id or against_type/against_id must already exist), nor does it route the agent to accelo_update_issue or accelo_create_task.

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