Enrich Leads With Open Profile Status

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

Even with readOnlyHint and openWorldHint annotations, the description adds substantial behavioral context: one LinkedIn request per lead with ~1s pacing, results stored in the lead_enrichment table keyed by member_id, search records never modified, enriched leads reused across searches, and resumable/idempotent behavior with failed fetches retried. This goes well beyond the annotations and is accurate to the operational reality.

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 information-dense but each sentence earns its place: the core purpose is front-loaded, followed by the technical constraint, cost model, storage behavior, and idempotency semantics. It avoids fluff and repetition while covering all needed operational details.

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, the description is complete: it explains why the tool exists, what it costs, where results go, how they are joined in, how idempotency works, and how to sample safely. The output schema exists, so return-value details are not the description's job. An agent has enough to select and invoke this tool correctly without further investigation.

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. The description adds value by explaining the cost implications of limit, clarifying that only_missing=true skips already-fetched leads and that failures remain pending for retry, and reinforcing how url_or_hash identifies the query. These details enrich parameter meaning beyond the schema's own descriptions.

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 a specific verb and resource: 'Add Open Profile / InMail status to a saved contact search.' It clearly distinguishes itself from closely related siblings like search_contacts and fetch_lead_profiles by explaining that this tool enriches saved query results with a field only available from profile requests.

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 gives explicit usage guidance: it is a separate opt-in tool rather than part of search_contacts, there is no bulk endpoint, users should start with a limit to sample before committing, and only_missing=true lets repeated calls walk through the query. This tells an agent exactly when and how to invoke it versus alternatives.

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