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

Annotations declare destructiveHint=true, so the agent knows this is a mutating operation. The description adds valuable behavioral context beyond that: the sensitive handling of SSN/ITIN (optional, pass once, never read back) and the response behavior ('says whether one is on file, never the number'). This is meaningful disclosure about privacy and data handling that the annotations don't cover. It doesn't fully describe all side effects (e.g., whether it overwrites existing profile fields), but the sensitive-data guidance is strong.

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 sentences, all information-dense. The first sentence states the core purpose, the second gives the critical SSN/ITIN handling rule, and the third clarifies the response behavior. No filler, no repetition of schema details. Front-loaded with the primary 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?

Given the tool's complexity (nested profile object, 4 parameters, output schema present), the description covers the essential behavioral aspects: what is recorded, the sensitive SSN handling, and the response semantics. The output schema exists, so return values needn't be described. The only gap is that it doesn't mention whether the profile is fully replaced or merged, and it doesn't explain the noSsn parameter, but these are minor against the strong sensitive-data guidance.

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 only 25%, so the description must compensate. The description explains the purpose of the profile fields (name, contact details, location) and the ssnItin parameter's sensitive nature, which adds meaning beyond the raw schema. However, it doesn't explain the noSsn boolean or the formationId wrapper, and the schema already provides patterns and enums for most fields. The description adds some value but doesn't fully compensate for the low coverage.

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 action ('Records who the founder is') and the resource ('on a formation'), and specifies the exact fields (name, contact details, location). It also distinguishes itself from sibling tools like formation_set_signatory and formation_set_shareholder_tax_identifier by focusing on the founder profile. The verb 'records' is specific and the scope is unambiguous.

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 on when to use this tool: when setting founder identity details on a formation. It also provides a specific usage guideline about the optional SSN/ITIN: 'ask for it only if the person offers, pass it once, and never read it back.' However, it doesn't explicitly name alternative tools or state when NOT to use it (e.g., when setting a signatory or shareholder tax identifier), so it misses the explicit exclusion that would earn a 5.

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