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

The description goes well beyond the readOnlyHint annotation by disclosing background execution, pacing (1-5 minutes between targets), LinkedIn safety limits, daily budget behavior, credit costs per target, deferral of targets beyond budget, and the single-slot concurrency constraint. It also explains the 'sample vs complete set' caveat for targets returning 10 mutual connections. This is rich behavioral context that annotations alone do not provide.

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 long but information-dense, with clear sectioning via <summary> and <returns> tags. It front-loads the core purpose and target format, then covers operational details. While it could be tightened, every sentence carries operational or behavioral information an agent needs; the length is justified by the tool's complexity.

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?

The description is complete for a complex background tool: it covers input format, output location and format, result interpretation caveats, cost/budget behavior, concurrency, and failure modes. The <returns> section documents the three possible status dict forms. Nothing an agent needs to call this tool correctly and interpret its results is missing.

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 schema already documents both parameters. The description adds meaningful context beyond the schema: it explains what kinds of identifiers are accepted (profile URLs, username slugs, provider_ids), how list_name is used as a bucket/slug for grouping results, and that reusing a slug accumulates into one list. This adds value beyond the schema's basic 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 states a specific verb ('find'), a specific resource ('warm-intro paths' via the user's 1st-degree LinkedIn connections), and the target input format. It clearly distinguishes itself from sibling tools like search_linkedin_people or search_linkedin_connections by focusing on the warm-intro path use case.

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 explicitly explains when to use this tool (to find warm-intro paths to target people), how to pass targets, how to read results via query_search_results, and what to do with partial results (treat 10-mutual-connection targets as a sample). It also gives operational guidance: confirm with the user before large lists, re-run tomorrow for deferred targets, and only one search at a time per account.

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