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

The description is rich beyond annotations: it explains that the profile fields are written as a group, that unset individual fields are CLEARED, that an ordinary rename skips the group, that profile updates are refused for LOVIE_FORMATION, and it explicitly states 'It writes, and it is neither idempotent nor destructive' and notes the required permission. No annotation contradiction exists.

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 long but every sentence adds necessary nuance about field mutability, clearing behavior, exceptions, and permissions. It is front-loaded with the primary action and fields, and then organically covers the edge cases. Slightly tighter wording would improve it, but it remains well-structured.

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 the presence of an output schema, the description does not need to explain the return shape. It fully covers the behavioral complexities an agent needs: group writes, clearing, refusal conditions, permissions, and idempotency. It is complete enough for an agent to call this tool correctly.

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?

With schema description coverage at 50%, the description compensates well by explaining the crucial aggregator semantics for the profile group—what happens when fields are unset, cleared, or skipped. It does not exhaustively detail every parameter, but the core decision-critical behavior for the 'company' parameter is clearly defined.

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 names the exact resources and fields ('patches mutable company fields in a single call: name, logo_url, aliases, and ... entity type, state, formation date, EIN and principal address'). It clearly differentiates this from siblings like company_get_company or formation_set_company_name by focusing on what UpdateCompany updates and in what context.

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 gives clear context: it is exposed so a founder can correct their own company by asking, and it explicitly states when profile fields are refused (source = LOVIE_FORMATION). It does not name alternative tools or give when-not-to-use instructions beyond that exclusion, but the guidance is sufficient for most selection scenarios.

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