Set primary provider

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

Annotations are sparse but present (readOnlyHint=false, destructiveHint=false). The description doesn't contradict annotations. It discloses the set-or-clear behavior via the primary boolean param, but doesn't explain what effect becoming primary has (e.g., does it change report defaults, routing?). With no annotations confirming safety profile details beyond the basics, moderate transparency is acceptable.

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 sentence that is efficient and zero-waste. The set-or-clear phrasing packs both behaviors into one concise statement. Well front-loaded and appropriate length.

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 tool with 4 params, 50% schema coverage, and no output schema, the description does some work but could add more. It explains the primary parameter's role but doesn't address what 'primary' means operationally or what the return value represents. However, given the relative simplicity of this configuration action and the decent schema descriptions for project_id and provider_id, this is adequate but not comprehensive.

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 50%, and the description's phrase 'Set or clear' provides meaning to the 'primary' boolean param that the schema doesn't state (the schema has no description for 'primary'). This is genuine added value. However, the other uncovered param (idempotency_key) has no schema description and no description help, though the name is fairly self-explanatory.

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 "Set or clear a provider as the primary project provider" clearly states the verb (set/clear) and resource (provider as primary project provider). It distinguishes from siblings like set_provider_enabled and set_provider_priority by specifying this is about the *primary* designation specifically. It's clear but slightly terse.

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 description implicitly communicates this alters project provider configuration, and the sibling set_provider_priority suggests priority vs primary are distinct concepts, but no explicit when-to-use or when-not-to-use guidance is given. No alternatives are named. The 'Set or clear' phrasing implies the primary param toggles it, but usage context around why you'd set a primary provider is absent.

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