rename_friend

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

No annotations exist, so the description carries the full burden, and it delivers the two facts that matter most: the rename is device-local, and the friend's real name is unaffected. It also discloses reversibility via the empty-string reset. It omits auth/permission requirements and error behavior, so it is strong but not exhaustive.

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?

A single tight sentence with three clauses, ordered as purpose → scope → reset mechanism, so the most important information is front-loaded. The parenthetical analogy is a small luxury but earns its place by clarifying intent. No filler.

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 simple two-required-parameter tool with no nested objects and no output schema, the description covers purpose, side effects, and the reset path. The only real gap is not telling the agent where to obtain userMid and what happens on an invalid MID, which is minor at this complexity.

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% — both newName and userMid already carry Thai descriptions including the empty-string reset semantics. The description restates the same empty-value behavior rather than adding new meaning. Baseline 3 is correct when the schema does the heavy lifting.

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 states a specific verb + resource (setting a friend's display name) and immediately scopes it: the change is local to the caller's device and does not alter the friend's real name. That scope detail differentiates it from any server-side profile tool, though it never explicitly names a sibling. Clear and specific, just short of the 5 bar that requires explicit sibling differentiation.

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?

Usage is implied rather than stated: the analogy '(like editing a friend's name in the app)' and the instruction to pass an empty value to restore the original name give a hint of the gesture. However, it never says when to prefer this tool, nor where the required userMid comes from (e.g., list_friends), and there are no exclusions. Implied usage only.

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