weeek_list_custom_fields

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

No annotations are provided, so the description carries full burden. It transparently discloses the notable behavioral quirk that results may include fields belonging to other projects (since tasks list every workspace field), and warns that writing to those is reported as an error. This is honest, non-obvious, and highly valuable behavioral context beyond any schema.

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?

Three sentences, all earning their place. Each sentence adds distinct value: what it lists, why the workaround exists, and the caveat about cross-project fields. Slightly dense but nothing wasteful — no filler.

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?

For a single-parameter listing tool with no output schema, this description covers the important essentials: what's returned, the empty-project edge case, how the data is sourced, and the cross-project caveat. There is no output schema to compensate, so the description carries full completeness burden and does so well.

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?

Only one parameter (project_id) exists, and the description names 'project' as the scope. Schema coverage is 0%, so the description compensates by clarifying semantics: it's a project-scoped read. However, it doesn't specify the exact format/type of project_id, though this is minor given the tool's self-contained single param.

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?

Clear verb+resource+scope: 'List the task custom fields visible in a project' with the exact fields returned (id, name, type, select options). Distinguishes from siblings: it's the read counterpart to weeek_manage_custom_fields, and it's clearly a listing tool (not a whoami/member/project lister).

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 describes the critical limitation: 'a project with no tasks yet returns nothing' — a key condition agents must know before invoking. Also explains the workaround mechanism (reads fields off a task because no schema endpoint exists) and the consequence of writing to other-project fields (reported as an error).

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