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

Annotations cover the safety profile (not read-only, not destructive, openWorldHint false), and the description adds genuinely non-obvious behavior: matching by email mutates an existing contact instead of creating a duplicate. It does not mention whether this is scoped to the calling user's private contacts only or whether failures occur on malformed emails, so it falls short of full disclosure.

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?

Two compact sentences: the first states the action and the upsert edge case, the second states usage and provenance constraints. Nothing is redundant and the core behavior is front-loaded.

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 no output schema and annotations already declaring the safety profile, the description covers what an agent most needs: when to call it, that it should not fabricate data, and that duplicate emails update rather than duplicate. Only minor gaps remain (return value shape, any validation/auth requirements).

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 0%, so the description must carry parameter meaning; it adds important semantics for email (an existing contact with the same email is updated, i.e. upsert behavior). The other five parameters (firm, name, notes, title, linkedin_url) are left entirely to their self-describing names, with no format guidance such as LinkedIn URL shape.

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 and resource — adds an investor to the user's private contacts — and clarifies the storage scope ("private contacts"), which separates it from sibling add_cap_table_stakeholder without naming it. It does not explicitly point at the sibling it differs from, so a 5 is not warranted.

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?

"Use only when the user asks" gives a clear activation condition, and "use details the user gave, never invented ones" is an explicit data-provenance constraint rather than an inference. No alternative tool is named for the related case (e.g. adding a cap-table stakeholder), which keeps it below a 5.

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