update_entity

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

Annotations already provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, indicating it is a mutating, non-idempotent, non-destructive operation. The description adds that it can both create and update, which is useful behavioral context beyond annotations; it implies persistence of changes)Skip. However, it doesn't disclose that 'create' auto-generates an ID (that is in schema) or that updates might overwrite existing properties in a way that could be non-destructive. With annotations covering the harmful side, the description adds some value but not extensive behavioral detail.

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 a single sentence that is informative and front-loads the main action. It is not overly verbose; it lists key fields but not every detail, striking a balance. It could be shorter but it's efficient for the scope. It earns a 4 because it conveys the core purpose without redundancy.

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?

No output schema, but the input schema is rich with nested objects and 13 parametersтная. The description covers the main fields but doesn't explain the create-vs-update semantics in detail (e.g., that providing an id updates an existing entity). It also doesn't mention any return value or side effects, which is common for such tools. Given the complexity, it is minimally adequate but has gaps in clarifying behavior and prerequisites.

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%, meaning all 13 parameters have descriptions. The description lists fields like position, orientation, bounding box, custom properties, tags, and confidence, which overlaps with schema. It doesn't add new meaning beyond listing them; for instance, it mentions 'custom properties' but the schema already explains arbitrary JSON. For high coverage, baseline is 3, and the description doesn't significantly compensate.

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 clearly states a verb (Create or update) and a resource (entity in the spatial world model), and enumerates what fields can be set, distinguishing it from siblings like query_entities or set_relation. It doesn't explicitly name alternatives, but the purpose is specific enough that an agent can infer it is the primary write tool for entities.

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 implies dual behavior (create vs update) but does not explicitly state when to use this tool versus query_entities (for reading) or other spatial manipulation tools like manage_spatial_spec. It mentions 'create or update' but lacks explicit conditions, such as 'use when you need to add a new entity or modify an existing one's properties.' It also doesn't state when not to use it (e.g., for queries). Some usage is implied but not explicit.

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