motion_custom_fields

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only lists required parameters per operation and does not mention side effects (e.g., destructive nature of delete/remove), authorization needs, rate limits, or what the tool returns. The operation names imply behavior, but the description fails to add meaningful transparency beyond what the schema already conveys.

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 single dense sentence but efficiently packs all operation-parameter mappings into a compact form. It is not verbose and contains no filler, though breaking it into a list or bullet points could improve readability. Overall, it 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 the tool's complexity (7 operations, 12 params, no output schema or annotations), the description provides solid coverage of required parameters but lacks high-level context about what each operation does beyond the verb (e.g., return values, error conditions, or behavioral side effects). It is adequate for invoking the tool correctly but not rich in context.

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 has 100% coverage, so baseline is 3. The description adds value by grouping parameters by operation (e.g., 'create: workspaceId/workspaceName + name + field') and clarifying conditional requirements like 'options[] also required for select/multiSelect'. This cross-cutting mapping is not immediately apparent from individual parameter descriptions and helps the agent understand dependencies.

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's purpose: 'Manage custom fields for tasks and projects.' This is a specific verb+resource that distinguishes it from sibling tools like motion_tasks and motion_projects. It also enumerates all supported operations, making its scope immediately evident.

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 provides clear context for when to use the tool (for custom field operations on tasks/projects) and lists operation-specific required parameters, implicitly guiding the agent. However, it does not explicitly mention alternatives or exclusions, though the unique domain makes that less necessary.

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