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

Annotations already state non-read-only, idempotent, non-destructive, so the safety profile is covered. The description usefully resolves the 'toggle' ambiguity by making it a set-state operation, but says nothing about permission requirements, behavior for unknown slugs, or failure modes.

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 sentences, front-loaded with the operation and followed by the parameter semantics. Nothing is padded or redundant.

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 small state-setting mutation with full annotations, a complete schema, and an output schema, the description covers what an agent needs to call it correctly. The only gap is failure behavior for a missing group or ambiguous tenant, which the schema partly mitigates.

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 three parameters, including the conditional tenant_slug rule, are already documented. The description's pin/unpin explanation of pinned duplicates the schema text rather than adding syntax or edge-case guidance, so the baseline of 3 applies.

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 gives a specific verb (toggle) and resource (a group's sidebar-pin state), which is enough to separate it from kb_projects_pin_toggle and kb_groups_update. It stops short of naming any sibling explicitly, so differentiation relies on the reader noticing the 'group' scope.

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?

The second sentence explains how to use the pinned parameter, not when to prefer this tool over alternatives such as kb_groups_update or kb_projects_pin_toggle. Usage is only implied by the pin/unpin framing.

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