auth_set_claims

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

With no annotations, the description carries the full burden and does disclose the key mutation semantics: replace overwrites the entire claim set, merge touches only the supplied keys, and a null value deletes a key. It omits side effects an Auth caller would care about, such as whether existing ID tokens must be refreshed and how errors are surfaced.

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 front-loaded sentence that leads with the operation and then the mode semantics; every clause carries information, with no filler or repetition of schema fields.

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?

Covers the core claim-setting semantics for a mutation tool, but with five parameters including a multi-user 'uids' array and no output schema, it says nothing about per-user behavior or what a call returns. Adequate for calling the tool, incomplete for predicting the outcome of a multi-uid call.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: what 'replace' and 'merge' actually do and the null-value removal convention inside the claims object. It adds nothing about uid vs uids vs tenant selection, which the schema already handles.

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 specific verb and resource ('Set an Auth emulator user's custom claims') and immediately disambiguates the two operating modes, replace vs merge, plus the null-removes-key rule. An agent can distinguish this from siblings like auth_remove_claims or auth_mint_token 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?

Gives clear selection guidance between the two modes and explains that replace mirrors the Admin SDK's setCustomUserClaims, which tells the caller when replace is the right choice. It does not name alternatives or state prerequisites such as the user having to exist or the emulator being active.

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