companies_set_active

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states this is a mutation (PUT, sets active state), that it returns the updated company list, and that it requires COMPANY_EDIT permission. It's clear this changes organization-wide state. While it doesn't specify whether this action is reversible, the description covers the key behavioral traits: side effect (state change), required permission, and return behavior.

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 a compact 3-sentence structure: what it does, the endpoint and return behavior, and the prerequisite permission/usage hint. Every sentence carries meaningful information. Slightly denser than strictly necessary (endpoint path could arguably be redundant with the tool's purpose), but it stays efficient and front-loads the core action.

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 single-parameter tool with complete schema coverage and no output schema, the description is reasonably complete: it discloses the mutation, the permission requirement, the return value, and the standard prerequisite (companies_list). Given the simplicity of the operation, this is sufficient. The only minor gap is not specifying behavior in edge cases (e.g., invalid companyId), but that's typically unnecessary for such a tool.

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 companyId parameter. The description adds value by explaining the parameter's role ('mark as the active company for the organization'), the endpoint format ({uuid} in the path), and by telling the user to find UUIDs via companies_list. This complements the schema's field description rather than merely repeating it.

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 clearly states the specific action (set active company by UUID), the HTTP endpoint (PUT /api/v1/companies/{uuid}/set-active), and its return value (updated list of all companies). It distinguishes itself from siblings like companies_set_active vs companies_select (which likely involves user context switching) and companies_toggle_sync (toggling sync, not active state). The verb+resource+scope is specific and clear.

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 a clear usage directive: 'Use companies_list first to find available company UUIDs', which establishes a prerequisite workflow. It states the required permission (COMPANY_EDIT) and implies this operates at the organization level. However, it doesn't explicitly articulate when NOT to use it vs alternatives like companies_toggle_sync or companies_select, though the prerequisite and endpoint detail offer reasonable guidance.

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