Update Federation Issuer

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

Beyond the destructiveHint=true annotation, the description explains exactly what is destroyed — existing workload access tokens are invalidated — and that omitted optional fields are cleared rather than preserved. It also discloses the auth requirement (org admin via user session or OAuth with full_access) and explicitly rules out API keys and workload tokens, context the annotations cannot convey.

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?

Five short sentences, each carrying distinct load-bearing information: request semantics, field-clearing behavior, side effects, return shape, and authorization. The most decision-critical facts (PUT semantics, omitted fields cleared) are front-loaded and nothing is repeated from the schema or annotations.

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 no output schema, the description correctly compensates by enumerating the returned issuer object fields, and it covers auth, side effects, and mutation semantics for a 7-parameter destructive tool. The remaining gap is parameter-level detail for the low-coverage schema (name, organization, id), which is the one area an agent could still get wrong.

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 only 29%, so only jwks_url and issuer_url carry inline meaning. The sentence "Omitted optional fields are cleared" adds real semantics for the three optional parameters (jwks_url, description, jwks_source), but name, organization, and id get no explanation in either place — e.g., whether organization is a slug or ID, or the format constraint on name.

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?

"Replace the complete configuration (PUT), not a partial update" states a specific verb (replace/update) and resource (federation issuer config) and immediately resolves the ambiguity with update semantics that most similar tools leave implicit. Combined with the name and title, an agent knows exactly which operation this is and how it differs from a read (get-federation-issuer) or a rule update (update-federation-rule).

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 clearly establishes the when/when-not boundary: full replacement only, omitted optional fields are cleared, and API keys or workload tokens cannot call it. It stops short of naming an alternative tool (e.g., get-federation-issuer to read current values before replacing), so the agent must infer the read-modify-write workflow from the sibling list.

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