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

Beyond the annotations, it explains case-insensitive matching by name, creation versus update behavior, per-platform handle replacement with omitted platforms preserved, and merge_existing=false leaving existing rows untouched. This clarifies exactly what the destructive update does and what is preserved, which is strong behavioral context.

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 front-loaded with what the tool does and how matching works, then adds update semantics, the intended use case, and the allowed handle keys. It is dense but every sentence contributes useful selection or invocation context.

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 six-parameter nested-object mutation with destructiveHint=true, the description covers purpose, matching, merge behavior, and handle constraints. It does not fully describe the success response shape, though schema notes on merge_existing partially cover that.

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 100%, so the schema already documents all six parameters, including allowed handle keys and merge semantics. The description reinforces the handle key restriction but adds little parameter meaning beyond what the schema already provides.

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 states a specific CRUD-style operation on a well-defined resource: creates or updates a person in the workspace mention list used by the upload flow. It clearly separates this from generic post/upload tools, but does not explicitly contrast with siblings such as list_workspace_people or resolve_linkedin_mention.

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?

It gives a concrete when-to-use scenario: filling in a podcast guest's LinkedIn/Facebook/YouTube handles before drafting so the mention popover is ready. It does not state when not to use it or name alternative tools, so it falls short of the 5-level alternative guidance.

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