competitor_get_overview

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

With no annotations, the description carries the full behavioral disclosure burden. It transparently discloses the null return behavior and the specifics of short/medium detail levels (fields included), which adds valuable context beyond the schema. However, it doesn't describe error conditions or the full content of 'raw', leaving a small gap.

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 only two sentences, front-loaded with the primary purpose, and every clause earns its place. It efficiently conveys the resource, the detail levels, and the null-case fallback without any fluff or repetition.

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?

Given the absence of an output schema and annotations, the description compensates reasonably by explaining the null return and the detail level output differences. It does not fully describe the 'full' raw structure, but the schema's detail parameter already hints at 'complete object'. For a relatively simple get tool, this is adequately complete for an agent to know what to expect.

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?

The input schema already provides 100% coverage with detailed descriptions for both parameters, including the detail enum semantics and brandId default. The description adds minor extra meaning by specifying the exact fields for short ('id,status,generatedAt') and medium ('summary excerpt'), but this largely overlaps with schema content. Baseline of 3 is appropriate since schema does the heavy lifting.

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 uses a specific verb 'Get' with a clear resource 'competitive landscape overview', and immediately distinguishes itself from the sibling tool 'competitor_generate_overview' by mentioning it for the null case. This clearly identifies the tool's function and differentiates it from related competitor tools.

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 provides an explicit when-not situation: 'Returns null when no overview exists — use competitor_generate_overview to create one.' This gives clear guidance for a common edge case, though it doesn't elaborate on when to use this over other competitor tools like competitor_get_comparison. The context is sufficient for most use cases.

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