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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false) by disclosing the paid external lookup model with concrete prices ($0.001–0.015, up to ~$0.03 with deep), the GitHub-first free tier ordering, and the 30-day result cache. This is exactly the cost/rate/state context annotations cannot express, and it is what lets an agent decide whether a call is affordable.

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?

Four dense sentences, front-loaded with the return payload then cost then guidance; no fluff. The only clause that does not earn its place is '(cached=true is free)', which misnames a parameter and adds confusion rather than signal.

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?

There is no output schema, so the description must carry the return contract — and it does, listing every field plus the source/confidence metadata per field. It also covers cost, caching lifetime, and the deep-mode escalation, which is everything needed to call this correctly.

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 baseline is 3; the description usefully ties deep=true to extra X-bio and name+company searches and explains the refresh/cache cost tradeoff. However it references a 'cached=true' switch that does not exist in the input schema (the real parameter is refresh), which could lead an agent to pass an invalid argument. That stale reference offsets the added value.

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 by scoping to a single GitHub user and enumerates exactly what is returned (LinkedIn URL, headline, current companies, work email, X profile, each with source and confidence). 'For one GitHub user' immediately separates it from bulk siblings like find_people_for_role or analyze_github_users. An agent can tell what this returns without opening the schema.

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 explicit when-to-use guidance ('people the user is seriously considering') and an explicit when-not ('not on every name in a list'), plus cost-based selection guidance for deep=true. It never names a specific alternative sibling (e.g., get_person_evidence or analyze_github_user) to route to instead, which keeps it short of a 5.

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