Update Foundry Entity

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

Annotations (openWorldHint, idempotentHint) provide some context, and the description adds useful behavioral detail: it is a partial update (only changed fields are sent) and can target either a UUID or the current selection. It does not explain side effects on persisted world data or auth behavior, but with annotations present this is adequate.

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?

Two short, focused sentences. There is no filler or repetition, and the key usage instructions are front-loaded.

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?

With six parameters, a nested data object, and no output schema, the description is too thin to be fully actionable. It does not explain how uuid and selected interact, when to use actor or userId/clientId, or what the tool returns after an update. The schema lists parameters but the description fails to synthesize them into a coherent usage flow, leaving meaningful 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?

The input schema already covers 100% of parameters with descriptions, so the schema carries the heavy lifting. The description reinforces the meaning of 'data' by saying 'only fields to change,' but it does not clarify interactions between uuid, selected, actor, or userId beyond what the schema states, so no significant extra semantic value is added.

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 ('Update') with a clear resource ('existing Foundry entity') and two targeting modes (UUID or current selection), which immediately distinguishes it from siblings like create, delete, and get. 'Pass only the fields to change' further clarifies the PATCH-like intent.

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 phrase 'existing entity' makes clear it is not for creation or deletion, and 'by UUID or current selection' explains the primary usage modes. However, it does not explicitly mention when to prefer this over foundry_modify_actor or other siblings, so it stops short of full when/when-not guidance.

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