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

Annotations declare readOnlyHint=true, and the description aligns with that (it's a read/synthesis operation). The description adds valuable behavioral context: it is a priced B2 cross-catalog synthesis call ($0.05 per call under pay-as-you-go; included in Understanding and Influence plans), and it references apis://prices for details. It also discloses that the 'context' parameter is never used for ranking and is only read when a result is wrong. This goes beyond the annotation.

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 compact and front-loaded: the core purpose is in the first sentence, followed by pricing and a pointer to more details. Every sentence adds distinct value (scope, content, cost, plan inclusion, pricing reference). No filler or repetition of schema details.

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 retrieval tool with one required parameter and no output schema, the description covers the essential context: what the tool returns, what it costs, and how the optional context parameter behaves. It doesn't describe the output structure, but there is no output schema and the description's list of contents (scores, stack, history) gives a reasonable picture. A small gap is not specifying the format of 'slug' (e.g., company identifier vs. name), but the sibling find_company_insights likely handles that discovery.

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 50%: 'slug' has no description in the schema, but the tool description makes clear it identifies the company ('for one company'). The 'context' parameter is fully explained in the schema, and the description reinforces its purpose. The description compensates for the undocumented 'slug' parameter by establishing the resource being addressed.

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 with a clear verb and resource: 'Full demand-side profile for one company.' It enumerates the specific content (40-dimension readiness scores, adopted stack, per-quarter history), which distinguishes it from sibling tools like find_company_insights (search/discovery) and get_provider (supply-side). The 'UNDERSTANDING' label and pricing context further clarify its role.

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 implies when to use it: when you need a full demand-side profile for a single company, as opposed to searching for companies (find_company_insights) or getting supply-side provider data (get_provider). It does not explicitly state 'use this instead of X' or list exclusions, but the scope is clear enough for an agent to select it correctly.

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