resolve_conflict

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds the substantive behavior the agent actually needs — that supersede resolutions keep one entry, both_valid keeps both, and merge replaces both with merged_entry. It also flags that a note is required. Doesn't say whether resolutions are reversible or what the response confirms.

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?

Four tight sentences: what it is, the safety gate, the entry ordering, then each resolution mode. Front-loaded with the trigger condition and zero 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?

With an output schema present the description needn't explain return values, and the mutation semantics and enum mapping are covered. Minor gaps remain around merged_entry requirements and failure modes when the conflict is already resolved.

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 coverage is only 20%, and the description compensates by spelling out the meaning of all four resolution enum values and the a/b age ordering, which the schema leaves as a bare enum. It still doesn't explain conflict_id provenance or the fields expected in merged_entry, so one required param and the nested input remain schema-only.

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?

Names a specific verb (resolve) and resource (a server-reported conflict of two active entries on the same topic), and immediately explains the a/b ordering that makes the operation meaningful. An agent can tell this apart from remember/update_state without opening the schema.

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?

"Ask the user first unless the answer is clear from the conversation" gives an explicit precondition for invoking it. It doesn't mention what to do if the conflict is stale or how to find conflicts, and names no alternative tools, so it falls short of full when/when-not coverage.

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