Digital Experts Hypotheses

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

With no annotations, the description carries the full burden. It does disclose the shape of the return payload (fields, citation sentence, source_url) and instructs quoting the citation, which is genuine behavioral context. However, it says nothing about error handling for an invalid id, permissions, or rate limits.

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 compact sentences, front-loaded with the core purpose, followed by one actionable instruction. No filler 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?

There is no output schema, so the description must describe return contents, and it does so thoroughly (job story, audience, offer, creative text, budget, metrics, conclusion, citation, source_url). It is short only on error/prerequisite behavior, leaving a small gap for a retrieval tool with no annotations.

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% for the single id parameter, and the schema already supplies the 'h-22788a' example format. The description repeats that example but adds no new meaning, 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?

States a specific verb and resource ('Full card of one hypothesis or test-wave summary by id') and enumerates the returned fields, so the agent knows exactly what it gets. It implicitly contrasts with search_hypotheses by being a single-record-by-id lookup, but never names the sibling.

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?

Usage is implied rather than stated: the id-based retrieval pattern implies you first use search_hypotheses to obtain an id, and the schema confirms this. There is no explicit when-to-use, when-not-to-use, or named alternative in the description itself.

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?

With no annotations and no output schema, the description carries the full disclosure burden and largely meets it: it states coverage (all 18 niches), the exact metrics returned, and the qualifying scope ('over tested hypotheses'). It does not explicitly confirm read-only behavior, but the 'list' framing and fixed small cardinality make the safe-read profile unambiguous.

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, correctly front-loaded with what is returned, then the usage cue, then the attribution requirement. Every clause carries information; nothing is padding.

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 no output schema, the description must convey the return shape, and it does so precisely (counts: hypotheses/tested/worked; medians: cost per subscriber, cost per lead, USD). It also supplies the citation/license obligation an agent needs, leaving nothing material 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 tool takes zero parameters, so the baseline is 4. There is nothing to document, and the description correctly does not invent parameters.

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 gives a specific verb-plus-resource ('All 18 niches of the Digital Experts hypotheses base') and enumerates exactly what each row contains (counts and medians). It is clear what the tool returns, but it never names or contrasts with the sibling niche_stats, which sounds like a closely related niche-scoped tool.

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?

'Start here to pick a niche' gives an explicit entry-point instruction that tells the agent when this tool is the right first call. It does not name alternatives or state when not to use it, so exclusion guidance is absent, but the usage context is 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?

With no annotations, the description carries the full disclosure burden for what is essentially a static document fetch. It discloses the scope of content well (measurements, verdict logic, limitations, license), giving the agent a solid sense of what reading it yields, though it doesn't state the return format or any access constraints.

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?

A single sentence front-loads the resource and then dense-lists the covered topics, ending with the actionable directive. No sentence is wasted.

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 zero-parameter documentation tool with no output schema, the description explains well what content the document contains and why it matters. It stops short of describing the return format, but the enumerated content scope is sufficient for an agent to decide whether to call it.

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 tool takes zero parameters, so there is no parameter semantics to document and the baseline of 4 applies. No misleading parameter hints are present.

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 resource (the methodology of the Digital Experts base) and enumerates its content precisely: hypothesis origins, the $50–500 exploratory test, measurements, verdict rules, limitations and license. This clearly distinguishes it from the data-returning siblings (get_hypothesis, list_niches, niche_stats, search_hypotheses), which fetch records rather than meta-documentation.

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 closing instruction 'Read before interpreting the numbers' gives explicit contextual guidance on when to consult this tool relative to the numeric siblings. It does not name the alternatives explicitly, but the intended sequencing is clear from the wording.

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?

With no annotations, the description carries the full burden. It usefully discloses the return content and a behavioral cap (only the 10 cheapest-lead tested hypotheses are included), which is genuine beyond-schema information. However it says nothing about access requirements, whether results are cached/computed live, or how expensive the call is relative to the raw search tools.

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?

One dense sentence lists the returned fields first, then the parameter format, so it is front-loaded with the most decision-relevant content. It is a long enumerative sentence rather than clean prose, but nothing is wasted and nothing is padded.

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?

There is no output schema, so the description must describe the return, and it does so field-by-field including units (USD) and the truncation to 10 hypotheses. Combined with 100% parameter coverage, an agent has enough to call it correctly; only error behavior and cost/auth context are absent.

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 baseline is 3, and the description exceeds it by giving concrete literal formats for the single parameter ('biznes-prodazhi' or 'Бизнес'), clarifying that either a slug or a Russian display name is accepted. That is meaningful added value beyond the schema's terser 'slug or name, see list_niches'.

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 enumerates the specific payload returned (hypotheses, tested, worked, median CPC/CPS, budget, years, 10 cheapest-lead hypotheses), which is far more than a tautology and lets an agent distinguish it from list_niches or search_hypotheses. The pairing with the required 'niche' key makes the resource scope unambiguous. It lacks an explicit verb framing ('returns a summary for one niche'), but the resource and content are clear.

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?

No statement of when to use this versus list_niches (to discover niches) or search_hypotheses (to find hypotheses across niches). The only routing hint is the parameter note pointing at list_niches, which is incidental. An agent must infer that this is the per-niche aggregation endpoint.

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?

No annotations are provided, so the description carries the full burden, and it does meaningfully disclose the return shape (compact rows listing id, title, niche, year, cost per subscriber/lead, verdict, source_url) rather than leaving it opaque. It does not cover auth, rate limits, or pagination behavior, which keeps it short of a 5.

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 sentences, front-loaded with the core capability, then the return shape, then the sibling pointer and language tip. No filler; every clause earns its place.

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 7-parameter search tool with no annotations and no output schema, the description supplies the return-format detail and the alternative-tool routing that the structured fields cannot. The remaining gap is the undocumented subset of filter parameters, which slightly dents completeness.

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 57%, so roughly half the parameters are undocumented in the schema; the description compensates only partially by saying search covers titles, job stories, offers, creatives, and audiences and that filters exist. It adds the Russian-language hint (also present in the query schema description) but does not explain verdict, completeness, or cost semantics beyond what the schema already states.

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 (full-text search) and resource (hypotheses), enumerates the searchable fields, and names the sibling get_hypothesis as the alternative for the full card. An agent can distinguish it from get_hypothesis, list_niches, and niche_stats immediately.

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 routes the agent: use search_hypotheses for compact filtered rows, use get_hypothesis(id) for the full card. Adds a usage tip that Russian queries perform best. Lacks explicit when-not conditions beyond the sibling pointer, but the context is clear.

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