Sync Material Requirements Headers

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

The description goes far beyond the annotations by disclosing the 1000-entity limit with a 413 response, the link to sync-action documentation, defaulting behavior for company_id/project_id, the success return payload, and common error HTTP statuses (401/403/404). This gives agents concrete expectations about runtime behavior and error handling.

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 appropriately sized and front-loaded with the main purpose. Every subsequent sentence adds value: limits, partial-update behavior, defaults, return value, error handling, and API context. It is structured and avoids fluff, making it easy to scan.

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?

The description covers many behavioral aspects (limits, defaults, errors, partial updates) and mentions the return value, but it does not specify how to pass the sync payload (ids/origin_ids and fields). It relies on an external documentation link for the crucial details, leaving the description incomplete for an agent that must invoke the tool correctly with only this text and schema.

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 the two schema parameters are described, the description reveals that the tool needs additional parameters for ids/origin_ids and entity fields, yet these are absent from the input schema (which has additionalProperties: false). The description does not provide parameter names or structure for these core inputs, leaving agents unable to construct a valid request body despite having schema coverage for the two visible params.

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 opens with a specific verb+resource: 'Creates or updates material requirements headers identified using either ids or origin_ids.' This clearly states the tool's function and distinguishes it from sibling tools like sync_material_requirements_lines, which handle lines rather than headers.

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: it identifies headers by ids/origin_ids, supports partial updates ('Send only the fields you intend to change'), and mentions company_id/project_id defaults. However, it does not explicitly name alternatives or state when not to use this tool, so it misses the explicit exclusion guidance of a 5.

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