Connect provider

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

Annotations declare readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description explains that this tool both creates AND updates credentials, which is useful. However, with 10 parameters and no output schema, the description doesn't disclose what happens on update vs. connect (e.g., whether existing credentials are overwritten, whether test is performed), leaving significant behavioral ambiguity for a state-changing operation.

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?

The description is three sentences and front-loads the core purpose first. It packs provider categorization and self-hosted endpoint info efficiently. No wasted words, though the group of related fields (enabled/primary/priority/cost_per_check) could have been briefly referenced.

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 complex tool with 10 params, nested objects, no output schema, and low schema coverage, the description provides essential context (provider categories, endpoint explanation) but omits important behavioral details: idempotency semantics, overlapping top-level vs. nested credentials, effect of enabled/primary/priority flags, and whether this triggers a live connection test. It's adequate but leaves notable gaps for a state-changing operation.

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 carries a burden. It adds value by explaining the endpoint field's purpose (base URL for self-hosted providers) and enumerating valid provider_id values. However, it doesn't clarify the relationship between top-level login/secret vs. nested credentials.login/secret, nor the semantics of enabled, primary, priority, cost_per_check, or idempotency_key — a meaningful gap given low schema coverage.

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?

Purpose is clear: 'Connect or update credentials for a project provider.' The verb 'connect/update' plus resource 'project provider' is specific. It distinguishes itself from siblings like disconnect_provider, test_provider_connection, set_provider_enabled, and set_provider_priority by focusing on credential setup/update, though it doesn't explicitly name these alternatives.

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 provides useful context about which provider IDs are valid for each category (SERP: dataforseo/serpapi; analytics: ga4/gsc/plausible) and explains that self-hosted providers accept an endpoint. However, it doesn't state when to use this vs. alternatives like test_provider_connection, set_provider_enabled, or set_primary_provider, leaving usage boundaries somewhat implied rather than explicit.

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