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

Annotations already cover read-only and non-destructive behavior. The description adds context beyond those: it combines knowledge graph and web sources, and discloses that results may have a knowledge_graph or web_supplemental provenance. That helps the agent set expectations about result source quality and inconsistency, while not over-performing.

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?

Four short sentences, each earning its place: purpose, use cases, sibling alternatives, and provenance behavior. The main purpose is front-loaded and none of the text is redundant or promotional.

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?

The description is strong for scope and alternatives, but it never explicitly states the key invocation constraint that at least one filter is required. This is only buried in the ticker parameter description, and no fields are required in the schema, so an agent could plausibly call it with no filters. With 9 parameters and no output schema, the lack of a single-line invocation rule leaves a meaningful gap despite good overall prose.

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 100%, so the input schema already documents every parameter with examples ('labor costs', 'NKE', 'hotels'). The description reinforces the query intent and theme filters but adds little beyond what the schema already provides. This is a typical baseline-3 situation where the schema carries the parameter documentation burden.

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 ('Cross-company thematic earnings intelligence') and clearly differentiates from siblings by naming get_company_earnings and brand_tracker as alternatives. An agent can understand that this tool targets thematic, multi-company comparison rather than per-ticker or single-brand earnings.

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 tells when to use this tool: for multi-company comparisons, industry-level queries, or sector filters. It also names exclusions: single-brand earnings should use brand_tracker, and per-ticker structured analysis should use get_company_earnings. This gives the agent clear routing guidance without needing to open sibling schemas.

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