upsert_entity

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

With no annotations provided, the description carries the full burden. It discloses that the tool mutates data by creating or updating, describes the partial-update behavior (only provided fields change), and notes that the physical name is derived automatically. This covers the key behavioral traits, though it doesn't mention explicit side effects such as whether the operation is idempotent or what happens if an entityId doesn't exist.

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 sentences, front-loaded with the core action, and no redundant wording. Every sentence delivers meaningful guidance, making it exceptionally concise.

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 CRUD upsert tool with no output schema and no annotations, the description is largely complete: it defines create vs update semantics, notes required fields, and explains the derived physical name. Minor gaps exist (e.g., return value, error conditions), but these are not essential for tool selection and invocation.

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 schema covers only 25% of parameters (source is described). The description adds meaning to entityId (present = update, absent = create) and logicalName (required for create), and implies that the description parameter can be partially updated. However, it doesn't fully explain all parameters or compensate entirely for the low schema coverage.

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 the tool's dual purpose: create an entity when no entityId is provided, or update (upsert) an existing one when entityId is given. It names the specific resource (entity) and the conditional create/update behavior, which distinguishes it from sibling tools like upsert_attribute or upsert_relationship.

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 explicitly tells when to treat the operation as a create (no entityId, logicalName required) and when to treat it as an update (entityId given, only provided fields change). This gives clear guidance on the two usage modes, though it doesn't discuss alternatives or exclusions relative to other tools.

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