update_entity

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

No annotations are provided, so the description carries the full burden. It discloses a genuinely non-obvious behavioral quirk: addItems/removeItems on 'teams' is emulated client-side via read-merge-set due to a PB API bug, plus the mutual-exclusivity constraint. It still omits permission requirements, reversibility, and error/partial-failure behavior for a mutation tool.

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 front-loaded sentences, each carrying distinct information: purpose, mode selection, and a behavioral caveat. No filler or restatement of the name.

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 mutation tool with no annotations and no output schema, the description covers mode selection and a key quirk but leaves out permission/auth requirements, what a successful update returns, and how failures or conflicts are surfaced. Adequate but with clear gaps.

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 100%, so the schema already documents id, patch ops, and fields. The description reinforces the fields/patch distinction and adds the teams workaround note, but the mutual-exclusivity it mentions is already stated in the schema's own field descriptions, so added value is marginal over the baseline.

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?

States a clear verb+resource: 'Update an existing Productboard entity.' This distinguishes it from create_entity/delete_entity/get_entity siblings, though it doesn't explicitly name them. The scope of the update is well defined via the two modes.

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?

Clearly tells the agent when to use 'fields' (simple replacement) vs 'patch' (granular ops) and flags them as mutually exclusive. No exclusions around when not to use this tool versus sibling mutations, but the mode-selection guidance is explicit.

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