provider_setup

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

With no annotations, the description carries the full burden and does add real value: it warns never to paste an API key into arguments and states that local settings are inspected in masked form, plus that some providers return login commands instead of keys. What it omits is whether 'configure' mutates persistent settings, whether changes are reversible, and what 'check' actually verifies — a meaningful gap for a mutation-capable tool.

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?

One dense sentence enumerating the four capabilities followed by a short, well-placed safety rule and a caveat about login commands. Every clause carries information and the security warning is front-loaded rather than buried, though the first sentence is long enough that the action-to-capability mapping takes a second pass to parse.

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?

No output schema and no annotations, with 5 parameters at 20% coverage, means the description has to do a lot; it covers purpose and safety well but leaves the semantics of the required 'action' values underspecified. An agent knows broadly what the tool is for and the key security rule, but could still pick the wrong action (status vs check) or omit provider/model when configuring.

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 20%, so the description must compensate, and it only partly does: it implies key_env takes a variable name (reinforced by the 'existing key environment variable' phrasing and the no-paste warning) and gestures at model/base_url via 'configure a local model'. It never maps provider to the list/configure actions, and the distinction between the 'status' and 'check' actions is completely undefined, leaving the required action enum under-specified.

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?

Uses specific verbs over a clearly bounded resource set: list provider choices/guides, inspect masked settings, configure a local model or key env var, and discover models. An agent can tell this is a provider/credential configuration tool, not a test runner like run_test or doctor. It does not name any sibling tool to distinguish overlapping areas (setup, cli, doctor), which keeps it below a 5.

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 four described modes imply when to call it (listing providers, checking local settings, configuring, discovering models) and the closing note tells the agent that ChatGPT/CLI login choices yield local login commands rather than credentials. However, there is no explicit when-not guidance and no comparison against near-neighbors like setup, doctor, or cli, so the agent must infer routing.

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