Set agent credentials

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

Goes well beyond the annotations: all fields are validated before any write, unknown/Wiro-managed fields are refused, values are never echoed back, a running agent restarts to load new values, channels self-enable/disable based on required fields, saving turns on dependent scheduled tasks, and the Wiro project key is billed to the user's wallet. Authorization scope (team admin or deployer only) is also disclosed.

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?

Purpose and the describe-then-write protocol are front-loaded, and nearly every sentence carries a distinct rule. It is dense and long (~300 words) with a few soft edges (dashboard upload aside, playbook pointer) that could be trimmed, but the length is largely justified by the tool's side effects.

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 destructive, open-world mutation with side effects, the description covers prerequisites, validation behavior, permission model, hidden consequences (restarts, channel toggles, schedule activation, billing), and where to go next. An output schema exists, so return values need not be explained.

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 100%, so the schema already documents the three parameters; the description still adds meaning by explaining that `credential` alone triggers describe mode with no write, and that fields of one credential should be sent together. It does not add much on `fields` internals (parent_field/ordinal), which the schema handles.

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?

States a specific verb and resource ("Save credential fields on a deployed agent") and immediately enumerates the concrete credential kinds (API keys, bot tokens, account IDs, allow lists, OAuth app keys, browser-free tokens). An agent can distinguish this from update_agent or connect_agent_oauth without opening any schema.

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?

Gives explicit two-step protocol (describe-mode call with only `credential`, then call with `fields`), an exclusion rule ("Skip that call when list_agent_skills with name already showed the fields"), and a routing rule separating sign-in integrations handled by connect_agent_oauth from Gmail/Calendar/Drive, which are set here. It even names the read-only fallback (get_my_agent) for team members who lack save rights.

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