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

Substantial disclosure beyond the annotations: it names the required APIFY_TOKEN, the per-call credit cost, the no-request-to-LinkedIn behavior, the 7-day cache, the ~2-of-6 observed yield, the staleness of follower counts, and the fields that were removed. One tension worth noting: the text claims 'Read only' while readOnlyHint=false; the credit-consuming side effect the description itself admits plausibly explains the annotation (readOnlyHint false is also the MCP default), and destructiveHint=false supports the data-safety claim, so this reads as loose wording rather than a serious contradiction.

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?

Cost and purpose are front-loaded, then mechanics, then caveats, with almost no filler. It is dense and sentence-heavy (seven sentences, several long), and the removed-fields sentence could sit later, but every sentence carries information an agent needs.

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?

With no output schema, the description must carry the return contract and it does: page name, tagline, follower count when available, and the verification failure explanation. Auth requirements, cost, caching, and reliability limits are all present, leaving nothing an agent needs before calling.

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 already 100%, so the baseline is 3, but the description adds real meaning the schema does not: it explains that the page must be 'verified against the company's own site,' that failure rows carry a reason in linkedin_verification, and that company_name materially raises resolution odds. It does not restate the minConfidenceScore thresholds, which the schema already covers.

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 precise verb+resource+outcome: 'Resolve a company domain to its LinkedIn company page, verified against the company's own site, and return the page name and tagline.' It also names the exact inputs (domain, handle, company_name) and the verification gate, so an agent knows exactly what this tool produces and when it will produce nothing.

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?

It gives clear operating conditions: supply a domain to trigger homepage discovery or a handle to skip it, and supply company_name to raise the share of companies that resolve (score 80). It also explains that unverifiable pages are withheld with a reason in linkedin_verification. It does not state explicit when-not-to-use exclusions, but with no sibling tools there is no alternative to route against.

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