select_account

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

Annotations already mark this as non-read-only and non-idempotent, so mutation is expected. The description adds the stateful consequence ('Switch the active ad cabinet') and a recommended follow-up (check_session/get_account), plus the confirm gate. It does not detail side effects on the current session or whether switching is reversible, but for a simple selector this is adequate.

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?

Every sentence earns its place: main action, follow-up, and parameter guidance in a compact layout. No redundant clauses.

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?

Given only two params, an output schema, and no nested objects, the description covers the key sequence and data source. The only minor gap is a clearer statement of when not to call this tool (e.g., if already on the desired account).

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 0%, but the description documents both parameters: owner_id is sourced from list_accounts, and confirm is required only under strict write gate. This adds real meaning beyond the schema's bare string/boolean types. It doesn't specify confirm's default semantics beyond the schema.

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 action ('Switch the active ad cabinet') and signals its role as a precursor to check_session/get_account. It is clearly distinct from listing or reading accounts, though it does not explicitly name a sibling it is not.

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?

Tells the agent owner_id comes from list_accounts and that confirm is required under TG_ADS_WRITE_GATE=strict, effectively giving when-to-use conditions. It lacks explicit exclusions or when-not-to-use alternatives.

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