asana_set_custom_fields

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds that it uses 'correct type handling' for multi_enum and date objects, implying it transforms inputs as needed. It also says it fixes failures in the official MCP, which is a behavioral guarantee. The only missing detail is whether it partially updates or replaces all custom fields, but overall it discloses enough beyond 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?

Two sentences, zero filler. The primary purpose is stated in the first sentence, and the second sentence pinpoints the specific value-add (fixes for multi_enum and date wrappers). Every word 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?

Given only 2 params with full schema coverage, the description does not need to explain return values (no output schema). It covers what the tool does, its key behavioral nuance (type handling fixes), and its relationship to the official MCP. It could mention whether task_gid accepts a task ID or GID, but the schema says GID. This is complete for a straightforward mutation tool with idempotentHint.

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 100%, and the custom_fields parameter description explicitly lists how each type should be passed (enum GID, array for multi-enum, YYYY-MM-DD string for date, number, text). The description adds no additional param info, but the schema already carries the full burden. The tool description reinforces the type handling with 'correct type handling' and the fixes mention, slightly complementing the schema. Baseline 3 for full coverage, but the cross-reference to fixes elevates to 4.

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?

Description names a specific action (set custom fields) with a clear resource (task), and explains that it handles correct type passing (multi_enum arrays, date wrappers), distinguishing it from the official MCP approach. It clearly differentiates from siblings like asana_set_dates which handles dates on tasks rather than arbitrary custom fields.

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 notes it fixes issues that fail via the official MCP, implying it is the preferred tool for setting custom fields with complex types (multi_enum, date objects). It does not explicitly list when not to use it or mention alternatives, but the context of fixing official MCP shortcomings gives clear usage context. Sibling names like asana_update_project or asana_add_field_to_project don't overlap significantly, so no exclusions are necessary.

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