asana_batch_ops

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

The description states 'GET-with-default-fields ONLY' implying a read-only operation, but the annotations set readOnlyHint=false and idempotentHint=false, which contradict that. This creates confusion for an agent about whether the tool performs writes or mutations. The description contradicts the annotations.

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 consists of two compact sentences and a parenthetical that front-load the essential constraint (GET-with-default-fields ONLY) and the task of routing to alternatives. There is zero wasted verbiage, and the key limitation is placed immediately after the purpose.

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 simplicity of the tool (only one array parameter, no output schema) the description covers the main limitations and alternatives. It lacks a mention of response formatting or pagination, but since these are not prevalent for batch calls and no output schema exists, the main usage and constraints are well covered. A minor deduction for absence of response details.

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?

The schema already describes the 'actions' parameter at 100% coverage, but the description goes beyond that by explaining that only GET with default fields is allowed and that opt_fields/completed_since and PUT data are dropped. This provides critical extra semantic context about how parameters behave in the batch endpoint.

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 executes up to 5 Asana API operations in a single HTTP call, giving a specific verb (execute) and resource (Asana API operations). It additionally distinguishes itself from siblings by noting that filtered reads should use other tools and writes should use dedicated tools, making its purpose unambiguous against the large sibling list.

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?

Explicitly directs the agent on when and when not to use it: 'For filtered reads use asana_search_tasks/asana_list_*; for writes use the dedicated tools.' It also warns about the limiting behavior (options and PUT data are dropped) which defines the proper use case clearly.

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