set_chain_entity

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

Annotations declare destructiveHint=true and idempotentHint=true, signaling this overwrites existing entity assignment and repeated calls yield the same result. The description does not disclose that it overwrites (potentially destructive), doesn't mention null-clearing behavior, and doesn't confirm idempotency. For a destructive mutation tool, the disclosure is thin. However, annotations cover the core safety profile, so behavioral overlap exists – but the description adds almost nothing beyond them.

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?

Single concise sentence with no waste. Front-loads the action. Loses a point only because the parenthetical is ambiguous rather than clarifying.

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 destructive, idempotent, mutation tool with an output schema and zero top-level schema coverage, the description is too sparse. It omits overwrite semantics, null-clearing behavior, prerequisites, and error conditions. An agent lacks the context to invoke this confidently against siblings that also mutate chains.

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 0% at the top level, though the nested entity and chain_id have inline descriptions ('null = parent org', 'Chain identifier'). The outer 'params' wrapper is undocumented. The description's '(which subsidiary)' loosely mirrors the entity param semantics but adds no syntax, format, or validation details beyond what the inner schema provides. The low coverage means the description should compensate more than it does.

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 verb (tag) and resource (chain) with a qualifier about entity ownership, but the parenthetical '(which subsidiary)' is vague about whether this assigns, changes, or clears ownership. Among many sibling chain-mutation tools (rename_chain, set_chain_status, update_chain_metadata), the description doesn't clearly differentiate what set_chain_entity uniquely does versus updating metadata.

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?

No guidance on when to use this vs alternatives like update_chain_metadata or tag_ticket. The description doesn't say if this replaces an existing entity, requires the chain to be in a certain state, or how it differs from other chain-mutation siblings. An agent cannot infer usage conditions from this sentence alone.

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