enrich_company_profile

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

Annotations already declare readOnlyHint and openWorldHint. The description adds severe value by disclosing the cost model ('Cost: 1 credit', plus extra credits for parameters), cache behavior, and a hint that include/exclude toggles for enriched data. This exceeds the baseline.

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?

Two sentences, highly scannable: first states the primary function and output; second discloses cost. No wasted words; every phrase is informative.

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 read-only enrichment tool, the description, annotations, and comprehensive schema fully specify inputs, output expectations (structured data including profile fields), and pricing. No fidelity gaps beyond what's needed—no output schema exists but it's mentioned return is 'more' as a hint.

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?

Param schema has 100% coverage with detailed descriptions for each parameter, including enum values and cost implications. The description reinforces the semantics by noting that several parameters cost extra credits, aligning with the cost disclosure. Though the description itself doesn't add param detail, with full schema coverage, the burden is already met; plus it adds credit-cost transparency.

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?

Purpose is clear: 'Get structured data of a company profile from its professional network URL.' The specific verb 'Get' + resource 'structured data of a company profile' is distinguishable from siblings like enrich_company_lookup, though it doesn't explicitly name a sibling alternative—however, 'professional network URL' and the context fixate on URL-based retrieval.

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?

Clear context is given: requires a professional network URL, and it returns structured profile data. No explicit mention of when not to use it compared to alternatives like search or ID lookup, which would have earned a 5. The sibling list suggests alternatives exist but they're not named in the text.

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