vectis_enrich_contact

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

Adds significant behavior beyond the annotations: may incur Monid charges, retry semantics, pending state requiring refresh, and a trust boundary on returned provider content ('never instructions'). These are exactly the behavioral caveats an agent needs to call and interpret results safely. No contradiction with readOnlyHint, openWorldHint, or destructiveHint.

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?

Every sentence earns its place: main action, exclusions, cost, retry/idempotency, pending-state routing, and prompt-injection guard. It is dense but not padded, fronts with the core purpose, and keeps all cautionary notes in a compact sequence.

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?

Clearly covers cost, retry behavior, async/stale handling, and trust boundary, which are the most operationally important elements for this tool. The gaps are the exact shape of the enriched return value and the purpose of missionId, and there is no output schema to fill those in. Otherwise it is complete enough to invoke safely.

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?

The schema has 0% description coverage, so the description must compensate. It does enrich personId ('returned by Apollo') and requestId ('reuse for retries'), but leaves missionId entirely unexplained, forcing the agent to infer or guess at its role. This is a notable gap for a required 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 and resource: 'enrich a person ID', and grounds it in a concrete source ('returned by Apollo'). It also states what it excludes (personal emails and phone reveals), which sets it apart from email-finding and phone-reveal siblings such as vectis_find_email and vectis_verify_email. An agent can clearly identify when this tool applies.

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 strong context: use it for Apollo person IDs, reuse requestId for retries, and explicitly routes pending calls to vectis_refresh_call. It lacks formal when-not statements naming alternative tools for the non-pending use case, but the Apollo-personID trigger is a clear selection criterion.

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