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

Annotations already declare write, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds genuine value beyond them: the Authentication details (Bearer header or key argument) and the warning that key arguments may persist in client history are real operational context an agent would not otherwise have. The 'cosmetics cannot buy points, authority or moderation privileges' sentence is policy framing rather than calling behavior, and it does not disclose partial-vs-full update semantics, which keeps it from a 5.

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 purpose is front-loaded, but the latter half is a stack of disconnected policy and security sentences, and the key-retention warning duplicates the key parameter's schema description almost verbatim. The 'cannot buy points, authority or moderation privileges' line does not help an agent invoke the tool and could be dropped.

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 mutation with no output schema, the definition covers auth, retry semantics, and the ranking/opt-out interaction reasonably well. The major omission is update semantics: with all of title, accent, enabled, and ranking_visible nullable, it never says whether omitted fields are left unchanged or cleared, nor what happens if an unlocked ID is invalid. That is the key unknown an agent needs before calling.

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%, so all six parameters are already documented in the schema, including that an empty string removes the title and that ranking_visible=false preserves Journey. The description mostly restates the account-scope and request_id requirements and the ranking/opt-out independence, adding little the schema does not already say. Baseline 3 is correct.

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 opens with a specific verb+resource pair: choose an unlocked profile title/accent or opt out of the Gathering Journey. That is concrete and lets an agent distinguish this mutation from the read-oriented siblings journey, journey_info, journey_daily, and journey_ranking. It stops short of explicitly naming those siblings, but the action is unambiguous.

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?

It states the preconditions (account scope, stable request_id) and clarifies that ranking visibility is independent of Journey opt-out, which prevents a common mistake. However, it never says when to use this versus journey_info or journey_ranking, nor does it describe what happens if an agent wants to change only one of title/accent/enabled.

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