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

Annotations already declare the safety profile (mutation, not destructive, not idempotent, open world). The description adds one genuinely useful behavioral fact beyond them — "Keeps the signing key" — clarifying that an update does not rotate credentials, which matters against the rotate_key sibling. It omits version-conflict behavior, permission requirements, and whether settings is merge or replace, so it is only partially transparent.

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?

Two short, front-loaded sentences with zero filler; the mutation verb leads and the non-obvious guarantee follows. The extreme brevity is what costs it a point, since the second sentence is doing the work a fuller scope statement should.

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 six-parameter mutation with a required nested settings object, five required fields, no output schema, and only 50% schema coverage, this is under-specified. The agent has no guidance on version-mismatch outcomes, idempotency-key reuse semantics, or whether omitted settings are preserved or cleared.

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 50%, and the description supplies no parameter meaning at all — not for expected_version (which clearly encodes optimistic concurrency), not for environment, company, or installation, and not for the nested settings object. The most consequential parameter, expected_version, is left entirely to a bare integer schema.

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 and resource ("Update installation settings") and adds the concurrency qualifier "with the expected version", which distinguishes it from summer_messenger_installations_create and _list without needing their schemas. It stops short of explicitly naming which sibling to prefer, but the resource-level purpose 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?

There is no when-to-use or when-not-to-use guidance. Nothing tells the agent to prefer this over summer_messenger_installations_rotate_key for key rotation, or how it relates to _create. The reader must infer scope entirely from the tool name.

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