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

Annotations only declare readOnlyHint=false, so the description carries real weight here: it discloses that each change creates a new profile version, that open cases are reassessed against it, that null clears an answer, and that the required capability is company.settings_own. What it does not say is whether the reassessment is synchronous or eventual, or whether prior versions can be restored.

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?

Three compact sentences with the purpose front-loaded and the behavioral side effects after; there is little wasted wording. The phrase "keyed offering, service_area, ..." is slightly dense and would read better as an explicit list, which keeps it from a 5.

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 mutation tool with a deeply nested schema and no output schema, the description covers the mutation's side effects (versioning, case reassessment), the clearing convention, the capability requirement, and the shape of input. Nothing an agent needs in order to call it correctly is conspicuously absent.

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 50% (only company has a description), and the description compensates by naming the five answer keys and explaining the null-clears-a-field convention, which the schema does not state explicitly. It stops short of explaining the semantics of the less obvious keys such as confused_with and expected_complaints, leaving the agent to infer them from key names and enums.

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 uses a specific verb plus resource ("Record answers to the business-profile questions") and immediately disambiguates the write path from the sibling read path by naming get_business_profile_questions. It also enumerates the accepted keys, so an agent can tell exactly what this tool does versus the question-fetching sibling.

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 parenthetical reference to get_business_profile_questions gives implicit sequencing (fetch questions, then record answers), and "Any subset" clarifies that partial updates are legal. There is no explicit exclusion or statement about when not to use it (e.g., versus onboarding_status or set_approval_required), so it stops short of full when/when-not guidance.

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