people_enrich

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context by stating that the tool returns 'outcome, normalized output, raw provider data and _meta.tried' and that 'Provider API charges are billed directly to your provider account,' revealing that it invokes paid external providers. It does not, however, state whether the operation is read-only or what failure modes look like, and it omits any mention of the routing/waterfall behavior that the schema describes.

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 four short sentences, front-loaded with the core purpose and followed by a parameter hint, return shape, and a critical billing caveat. It is tight and free of fluff, though it covers slightly more ground than the two-sentence ideal seen in top-tier tools.

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—13 optional parameters, vendor routing, and no annotations—the description gives a reasonable overview but leaves gaps. It introduces the vendor pinning concept and billing, and the output schema covers return values, but it does not explain prerequisites (e.g., whether at least one identifier must be supplied), the default routing/waterfall behavior, or how this tool differs from its many people-related siblings, so an agent may not fully know how to formulate a call.

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?

Since schema description coverage is 100%, the parameters are already well documented and the baseline is 3. The description adds little beyond the schema: 'Use vendor to pin a provider' loosely restates the schema's description of the vendor parameter ('Pin one vendor or endpoint id instead of routing') without adding new semantic detail, so the value added over the schema is marginal.

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 opens with 'Everything known about one person: title, employer, location, profile links,' which clearly communicates that this tool retrieves a comprehensive profile for an individual. However, it does not explicitly name or contrast sibling tools like people_search or people_identity_resolve, so an agent must infer the distinction from the phrase 'everything known' rather than being told when this tool is the right choice.

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 offers no explicit guidance on when to use people_enrich versus alternatives such as people_search or people_contact_find. It implies its place through 'Everything known about one person,' but does not state exclusions or scenarios, such as 'use people_search to find people, use people_enrich once you have an identifier.'

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