asana_set_parent

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

With annotations already declaring mutating, non-destructive, idempotent, and open-world traits, the description adds useful behavioral detail: it explains the null-detach semantics and the optional sibling-ordering parameters. This goes beyond what annotations and schema state, giving an agent a clearer picture of the resulting hierarchy changes.

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 extremely economical — two sentences carry the purpose, both operating modes, and the optional sibling parameters — with the core verb+resource placed at the very start. No filler or redundancy; every clause earns its place.

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?

The description is adequate for a fairly simple re-parenting operation, but it omits critical edge-case context: what happens when parent_gid is absent (is the task left unchanged, or does it error?), and whether insert_before and insert_after are mutually exclusive or have precedence. With no output schema and limited annotations, these gaps leave an agent to guess about behavior in non-standard invocations.

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 only 25% (task_gid, insert_before, insert_after lack descriptions). The description compensates partially by clarifying that insert_before/insert_after refer to sibling GIDs and that parent_gid null means detach. However, it does not explain the behavior if parent_gid is omitted entirely, nor the interaction when both insert_before and insert_after are supplied, leaving meaningful semantic gaps.

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 the specific verb+resource combination 're-parent a task' and immediately explains the two functional modes (make it a subtask of parent_gid, or detach to top level). It clearly conveys the operation's scope, though it does not explicitly contrast with sibling tools such as asana_create_subtask, leaving differentiation implicit.

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 gives clear context for when to use the tool — when re-parenting an existing task — and covers both attaching to a new parent and detaching to root. However it never names alternative tools or conditions for preferring them (e.g., when creating a brand-new subtask instead of re-parenting). Usage is implied rather than explicitly routed.

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