Add Values To Custom Field

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

The description discloses crucial behavioral details: it creates a new record each time (non-idempotent), returns the new id with HTTP 201, and typically fails with 401/403/404 for token expiry, permissions, and unresolved ids. This goes well beyond the annotations (readOnlyHint=false, idempotentHint=false) and provides actionable error context.

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 moderately long but every sentence adds value: purpose, defaults, prerequisites, idempotency, errors, required params, and API endpoint. It is logically structured and front-loaded with the core purpose, though the endpoint/API section could be seen as extra for highly skilled agents.

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?

It covers the main workflow (append values, get new id), prerequisites, error responses, and API context. Without an output schema, the description still adequately explains the return and failure modes. The main gap is the lack of detail about the item type inside the values array, but this is minor given the tool's scope.

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?

Although schema coverage is 100%, the description adds important semantics: company_id's default behavior, field_id's prerequisite to resolve an existing parent record, and the 'append' behavior of values. This enriches the schema's basic URL/path descriptions.

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 uses a specific verb ('Appends') and clearly identifies the resource ('Custom Field with type select or multi-select'), which distinguishes it from sibling tools like remove_values_from_custom_field or create_custom_field. It also clarifies the scope of allowed field types.

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?

Provides clear context: company_id defaults to the procore_set_config value, and field_id must be resolved with the matching list tool first. It also warns that calling it again creates another record, which advises against unintended repetition. However, it does not explicitly explain when to use an alternative tool instead (e.g., update_custom_field for modifying existing values).

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