DDMarketer

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds valuable context about the selection criteria (commercial-intent, validated, past week, trending) which goes beyond the annotations and helps set expectations for the returned data.

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 concise sentences, front-loaded with the main action and intent. Every phrase adds value: 'highest commercial-intent', 'validated', 'past week', 'across all categories', and the usage guidance. No fluff or redundancy.

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 full schema descriptions, an output schema present, and read-only annotations, the description provides sufficient context for an agent to select and invoke the tool. It clearly states what the tool returns and when to use it. No significant gaps remain.

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?

Input schema covers both parameters fully (limit and category with descriptions), so schema coverage is 100%. The description does not add extra parameter-level detail, but it does clarify the default scope ('across all categories'), which aligns with the category filter. Baseline 3 is appropriate because the 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 clearly states it returns highest commercial-intent validated gaps from the past week, using a specific verb ('Return') and resource ('gaps'). It distinguishes itself from siblings (search_gaps is for filtered search, validate_idea for idea validation) by emphasizing the 'top' and 'trending' aspect across all categories.

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?

Provides explicit usage context: 'Use this when the user asks what to build with no particular market in mind, or wants to know what is trending right now.' It gives a clear when-to-use but does not explicitly mention when not to use or alternative tools, so it stops short of a 5.

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

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

Annotations already state readOnlyHint=true and openWorldHint=true, which the description does not contradict. It adds useful context about the nature of results (scored for willingness to pay) but does not disclose limitations like data staleness, pagination, or result completeness. Given the annotations cover safety, this is adequate but not rich.

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 two sentences: the first states the core purpose and defines a gap, the second gives direct usage guidance. Every word earns its place with no redundancy.

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, combined with a detailed schema and the presence of an output schema, gives an agent everything needed to decide when and how to use the tool. It explains the domain and purpose, while the schema handles parameter specifics.

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 schema covers 100% of parameters with descriptions, so the description does not need to compensate. The description's mention of 'by keyword' aligns with the 'query' parameter but adds no new detail beyond what the schema already provides.

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 clearly states the tool searches validated software opportunities by keyword and defines 'gaps' as real, recurring user complaints scored for commercial intent. It is specific about the resource (validated SaaS gaps) and the action (search), but it does not explicitly differentiate from sibling tools like get_top_gaps or validate_idea.

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 explicit usage context: 'Use this when the user wants ideas in a specific market, or asks what people complain about in some domain.' This gives clear when-to-use guidance, though it lacks explicit when-not-to-use or mention of alternative tools.

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

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

Annotations already declare readOnlyHint=true, so the agent knows it is a safe read. The description adds meaningful context about what the tool evaluates (complaints, commerciality, trends, verdict) and that it scores against a corpus, going beyond the annotations. This justifies a 4.

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: the first states the tool's function and output, the second gives usage guidance. Every word serves a purpose, with no fluff or repetition. Excellent structure.

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 a single parameter, existing output schema, and annotations, the description covers the core purpose and usage. It does not discuss limits or prerequisites, but these are not critical for this tool. Slight room for more (e.g., what 'verdict' means), but adequately complete.

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% and the parameter 'idea' is well-described with an example and character limit. The description adds no further parameter semantics—it merely restates 'specific product idea', so the baseline 3 applies.

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 ('Score') and resource ('product idea against the complaint corpus'), and enumerates key outputs (match count, commerciality, trending, verdict). It clearly distinguishes from siblings by focusing on validating an existing idea rather than discovering gaps.

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 explicitly states when to use it ('when the user has an idea already and wants to know if there is demand before building'), providing clear context. It does not explicitly name alternatives or exclusions, but the 'idea already' phrasing implies it is not for gap discovery, which is enough for a 4.

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