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

Annotations only tell the agent this is a non-read, non-destructive write. The description adds substantial context beyond that: the tool auto-canonicalizes the identifier so the caller must not hand-type one, findings are batched per person, company findings still attach to the person and require company_domain, and it even discloses the return shape (a count of saved rows). This is exactly the value-add expected over annotations.

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?

Front-loads the core action and purpose in the opening sentence, then uses summary/returns structure to separate intent from return value. The prose is somewhat dense and long, with a bit of redundancy around findings content, but nearly every sentence carries actionable information.

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 nested write tool with no formal output schema, the description covers the essentials: what to pass, how identifiers are handled, per-recipient batching, and the return count. It omits auth/permission requirements and any limits on finding volume, which are minor gaps given the mutation annotations already present.

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 baseline is 3, and the description adds real meaning: `person` must be a handle (LinkedIn URL / provider id / email) rather than a typed canonical identifier, and `company_domain` is required for subject_kind='company'. It clarifies the content-vs-source distinction for findings, though it does not explain the source enum values or the on_behalf_of parameter.

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 verb ('Persist/persist synthesized personalization research') and resource (prospect research findings on an agent) plus the reason it exists (visibility on the agent page). It is clearly the write counterpart to the sibling query_prospect_research, so an agent can distinguish them without opening either schema.

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?

Gives explicit timing and cadence: 'Call this after you synthesize a why-I'm-reach-out angle,' 'once per recipient,' and batching rules per recipient and across recipients. It also defines what NOT to pass (raw scraped post text or article abstract), which is a clear when-not condition, though it never names the read alternative query_prospect_research for comparison.

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