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

Annotations establish only the generic profile (not read-only, open-world, non-idempotent, non-destructive). The description adds genuinely new behavior: the operation is free and consumes no generation credit, url imports are restricted to paid plans, ~10 pages are read and only claims those pages actually make are used, and the call is a POST to /v1/companies.

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?

Front-loads the core action, then the three modes in parallel structure, then cost/return caveats. Dense but every clause carries information; the trailing API-reference URL is the only mildly expendable element.

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 six optional parameters and no output schema, the description does the necessary work: it explains mode selection, plan constraints, cost, and states what is returned ('Returns the company'). Return-shape detail is thin, but the caution to check extracted facts compensates for the missing output schema.

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 already 100%, so the schema carries the per-field meaning and the baseline is 3. The description adds value the schema does not: it maps parameter groups to named modes, clarifies that `text` accepts ANY freeform input (a pitch or rough notes), and that manual mode is the fallback when no url/text is supplied.

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 specific verb and resource ('Create a company/product context profile') plus the downstream purpose ('company-grounded generation'), so the agent knows what artifact is produced. It does not, however, differentiate itself from the sibling create_profile, which an agent must disambiguate on its own.

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?

Explicitly enumerates three mutually exclusive input modes (url, text, manual fields) with the condition that selects each, and states the plan gating (url import is paid, text and manual are all plans). It also gives a procedural guideline: verify extracted facts with the user before generating.

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