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

Annotations only provide readOnlyHint=true, so the description carries most behavioral disclosure. It adds meaningful traits: pricing per request and per record, a request cap, plan inclusion, matching across all rosters, and a pointer to estimate pricing. It does not add potential caveats like result ordering or response shape, but the added detail is substantial.

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 dense but each sentence adds value: purpose, industry vocabulary disambiguation, and pricing/plan guidance. It is front-loaded with the core purpose before cost details. Slightly heavy on pricing specifics, but still economically written for the information conveyed.

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?

For a browse/list tool with no required parameters and no output schema, the description gives enough to invoke it correctly: what it returns conceptually (profiled companies ranked by technology-readiness), how to filter, and cost behavior. It does not describe the exact response fields, but that is unlikely to block correct invocation.

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 description coverage is only 20% (only `context` is described), so the description must compensate. It does explain `q` as name search and `industry` as an insights industry name with a specific example and vocabulary warning. Page and limit are not described but their schema defaults/max are self-evident. Overall, it adds meaning where it matters most.

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?

Description states a specific verb ('Browse') and resource ('profiled companies (Fortune 1000)'), with clear filtering dimensions (name or industry) and ranking ('ranked by overall technology-readiness signal'). It also distinguishes itself from find_providers by explicitly calling out the different industry vocabulary, so an agent can tell them apart.

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 concrete context: industry must come from insights_industries, not the catalog slugs used by find_providers, and it matches all rosters a company sits on. It also mentions pricing, plan inclusion, and where to estimate cost. It does not explicitly contrast with get_company_insight, but the usage context is clear enough for selection.

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