weeek_manage_custom_fields

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

No annotations are provided, so the description carries the burden. It clarifies the ownership/scope semantics (which is genuine behavioral context beyond the schema), but doesn't address auth/required permissions, side effects of transfer (what happens to existing task data), reversibility, or response behavior. Given no annotations, this is a moderate disclosure that could go further.

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 a compact 3 sentences with the key concept (scope) front-loaded. It's efficient but packs in a lot without explicit structure; the action-to-param mappings are implied via schema descriptions rather than enumerated. Slightly dense for a complex 13-param, 9-action tool.

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?

This is a genuinely complex tool: 13 params, 9 actions in an enum, nested objects, multiple scopes, and per-action parameter requirements. With no output schema and no annotations, the description would need to spell out which params apply to which action to be fully complete. The scope explanation helps but the action-specific parameter requirements are left implicit in the schema, making the description incomplete for an agent to confidently drive this high-complexity tool.

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 high at 92%, so the schema already documents most parameters. The description adds the scope model explanation (scope + scope_id relationship) which goes beyond the schema's 'Where the field lives.' However, with 13 parameters and only ~92% covered, the description doesn't compensate for the undocumented remainder, and doesn't explain the action-to-parameter matrix (which params are needed per action).

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 lists specific verbs (Create, update, delete, move or transfer) tied to a clear resource (custom fields and their select options). It also adds the scope concept (board/project/global) that distinguishes this tool from siblings like weeek_list_custom_fields, and even names that reader tool explicitly.

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 explains the scope model (field belongs to one board, project, or global, set scope and scope_id accordingly), which is a crucial usage condition. It also calls out weeek_list_custom_fields as the reader for what a project's tasks show. However, it doesn't explicitly state when NOT to use this vs other manage_* tools or provide negative guidance.

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