DDMarketer

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

The description goes well beyond the annotations: it discloses the mandatory API key, account signup flow, Authorization header format, 24-hour free access, paid-plan limitation, and instructs the agent not to silently skip or lie about access. Since there is no output schema, this behavioral and access context is especially valuable.

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 core purpose is front-loaded in the first sentence, and the content list is compact. The authentication paragraph is long, but every detail is operationally necessary for the caller to successfully invoke the tool or choose the fallback path.

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 one-parameter tool with no output schema, the description is complete: it covers what is returned, the authentication prerequisite, free vs. paid access, and the fallback behavior when no key exists. None of the essential invocation context is missing.

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 documents the only parameter, id, as 'the gap id returned by search_gaps or get_top_gaps,' so schema coverage is 100%. The description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate.

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 states a specific action and resource: 'Return the full dossier for one validated gap' and enumerates what the dossier contains. It also distinguishes this from siblings by emphasizing the full dossier, which is broader than top gaps or search results.

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?

It clearly says when to use the tool, i.e., when a user wants depth on a specific validated gap, and it gives an explicit no-key alternative: offer the gap's public page. It does not explicitly name sibling tools as alternatives, but the context makes the appropriate use reasonably clear.

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 indicate readOnlyHint=true and openWorldHint=true, covering safety and scope expectations. The description adds useful selection behavior: gaps are 'validated,' 'highest commercial-intent,' and time-bound to the past week. However, it does not disclose details like ordering guarantees or possible empty results, though these are partially covered by the output schema.

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 with no filler. The first sentence states exactly what the tool returns and its scope; the second provides actionable guidance. Every word earns its place and the key behavior is front-loaded.

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?

This is a simple read-only tool with two optional parameters, a fully documented schema, an output schema, and safe annotations. The description covers what the tool returns, its time window, its ranking intent, and when to use it. Nothing critical is missing for an agent to invoke it correctly.

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 100%, so both 'limit' and 'category' are already documented. The description reinforces that the tool works 'across all categories' by default but adds no new parameter-specific meaning. A score of 3 is appropriate because the schema carries the parameter 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?

The description names a specific verb and resource: 'Return the highest commercial-intent validated gaps from the past week.' It also scopes the behavior with 'across all categories,' clearly distinguishing it from a category-specific or search-based tool. The purpose is immediately obvious and not a tautology.

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 gives explicit trigger conditions: use when the user asks what to build with no particular market in mind, or wants the strongest current signals. It implies that a market-specific query would be a different use case, but it does not explicitly name the sibling alternatives such as search_gaps.

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 and openWorldHint, covering the safety profile. The description adds useful context about the data being real, recurring complaints scored for commercial intent, and does not contradict the annotations.

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?

Three short sentences: the first states the operation, the second defines the domain and scoring, and the third gives usage context. No filler and information is front-loaded.

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 tool is simple, has a complete input schema, an output schema, and annotations covering read-only/open-world behavior. The description supplies the market/complaint context needed for selection; it is only slightly incomplete in not explicitly disambiguating against get_top_gaps.

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 schema already documents query, limit, and category. The description reinforces that query is keyword-based but does not add material meaning beyond what the schema 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 opens with a specific action ('Search') and resource ('validated software opportunities' / SaaS gaps), then clarifies what a gap is and how it is scored. This differentiates it from get_top_gaps (keyword search vs top list) and validate_idea (search vs validation) even without naming them.

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 gives a use condition: when the user wants ideas in a specific market or asks what people complain about in a domain. It does not state when not to use it or explicitly name sibling alternatives, so it falls just short of full routing guidance.

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 and openWorldHint=true, so the baseline is lower, but the description adds useful behavioral detail about what the scoring returns: complaint matches, commercial value, confidence, and a verdict. It accurately reflects a read-only analysis operation and does not contradict the annotations.

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, front-loads the core action and expected outputs, and the usage guidance is appended without redundancy. Every sentence contributes meaningful information.

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 tool has a single parameter, an output schema, and protective annotations. The description covers what the tool does, what it returns, and when to use it, which is complete for an agent to invoke it correctly.

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 100% and the schema fully documents the 'idea' parameter with a plain-words example and character limits. The tool description adds little beyond restating 'specific product idea,' so the baseline score of 3 is appropriate.

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 clearly identifies the resource ('a specific product idea against the complaint corpus') plus the key outputs: match count, commercial viability, confidence, and verdict. It is clearly distinct from the sibling tools by focusing on validating an existing idea rather than exploring or searching 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 the tool: 'when the user has an idea already and wants to know if there is demand before building.' This is strong usage guidance, though it does not explicitly name sibling alternatives or state when not to use them. The context is clear enough for an agent to route correctly.

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