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

Annotations already declare read-only and open-world access, so the extra detail is the important part: counts are framed as 'n of m answers', no traffic is promised, and drafts require human review before posting. It still doesn't say whether files are returned inline, as links, or persisted, which matters for a kit-generation tool.

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?

Front-loaded with the artifact list, then constraints, so little is wasted. The parenthetical for where-to-get-mentioned.md is long and slightly dense but carries real information about what the file contains.

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?

No output schema exists, so the description correctly spends its words enumerating the produced files and their contents, which is the essential return-value information. It is thin on delivery mechanics (download vs. inline) and on what happens if the report isn't finished.

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 single slug parameter is fully documented in the schema ('The slug from a previous call'), and the description adds nothing about it. With 100% schema coverage, 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?

States a concrete verb and artifact set: markdown files (product.md, competitors.md, ai-visibility.md, where-to-get-mentioned.md, channel-plan.md) derived from a finished report. This clearly separates it from sibling tools like recomention_report_get (returns the report) and recomention_rankings_get, since the output is a planning kit, not raw data.

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?

Gives sequencing ('Read README.md first') and a workflow guardrail ('Show the user every draft before anything is posted'), which implies it runs after a report is finished. It doesn't explicitly say which prerequisite tool produces the slug or what to do instead when there is no finished report.

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?

The annotations already declare read-only and open-world behavior, while the description adds useful return-shape detail: every product named, n of m counts, and verbatim answers. It also discloses that access is free, but does not describe error behavior or permissions beyond 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?

One compact sentence front-loads the scope and then lists the return contents. Every clause contributes without 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?

For a simple read-only GET with no output schema, the description explains the lookup key, the returned payload, and the cost. Together with annotations covering safety and open-world behavior, it is complete enough for correct invocation.

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 single required slug parameter already has 100% schema description ('The slug from a previous call'). The description only repeats 'by slug' and does not add format, source, or validation meaning beyond the schema, so the baseline of 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 states a specific verb ('Get'), resource ('one public AI ranking'), and lookup key ('by slug'), then enumerates the returned contents. The emphasis on 'one' distinguishes it from the sibling recomention_rankings_list without needing to name it.

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 implies use when you have a slug from a previous call and need a single ranking, and notes that it is 'Free'. However, it does not explicitly say when to use this versus recomention_rankings_list, nor does it state exclusions or prerequisites beyond the schema's slug hint.

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 safety profile is covered. The description adds genuinely non-structured traits that matter for agent planning: the data is 'public' (no auth implied) and 'Free', which is a cost signal not present in the schema or annotations. It stops short of describing result volume, pagination, or update cadence beyond the rough 'month by month' hint.

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 front-loaded sentence with a colon that expands into the essential detail, plus a one-word cost signal at the end. Nothing repeats the title or wastes tokens.

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 carries the burden of explaining what comes back, and it does so at a conceptual level: per-category product mentions attributed to AI engines over time. An agent knows the shape of the result well enough to decide whether to call it, though the actual response structure and whether all categories are returned in one call remain unstated.

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 nothing for the description to disambiguate and the baseline of 4 applies. The description correctly frames this as an unfiltered listing and does not imply inputs that the empty schema would contradict.

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 and resource ('List recomention's public AI rankings') and goes further by defining what a ranking actually is: which products AI engines name in response to buyer questions, tracked month by month. The one gap is that it never distinguishes itself from the sibling recomention_rankings_get, so an agent must infer that this is the collection-level call.

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 only implied: the plural/collection framing plus the sibling name recomention_rankings_get makes list-vs-get reasonably inferable, and 'Free' hints at a no-cost entry point. There is no explicit statement of when to choose this over the sibling or over recomention_reports_list, and no prerequisites are mentioned.

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, so the safety profile is covered. The description adds real context beyond them: enginesSkipped means no run occurred and must not be reported as a non-mention, and simulated:true flags test data. It omits what happens if the report is still generating or how large the payload can be, which keeps it at a 3.

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?

Front-loaded with 'A report as JSON' and then packed with high-value content in a single dense sentence. The trailing 'Free.' is a context-free fragment that does not earn its place, but otherwise there is no filler.

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 carries the return-value burden and does so well, enumerating every major field group and the two interpretation traps (enginesSkipped, simulated). Missing only lifecycle details such as error or not-ready states, which is minor for a one-parameter read.

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?

One parameter at 100% schema description coverage, so the schema already explains slug. The description adds nothing about slug format, reuse, or invalid-slug behavior, so it sits at the baseline for fully-documented schemas.

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 the resource (a report) and enumerates its contents precisely: overall score, per-engine runs, competitors named, cited sources, fix list, and Q&A. That specificity separates it from recomention_reports_list and recomention_rankings_get, though it never names a sibling explicitly and leaves the verb implicit.

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?

There is no statement of when to call this versus recomention_report_status or recomention_report_start, and no prerequisite such as 'only after the run completes.' The schema hint 'slug from a previous call' is the only workflow signal, and the dangling 'Free.' does not clarify when or why to use it.

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 description doesn't need to establish safety. It does add genuine behavioral context beyond them: the scope is the API key's owning account, results are ordered newest first, and 'Free' implies no credit/quota consumption. It omits pagination behavior and result size limits, which is the main remaining 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?

Two short fragments, front-loaded with the resource and scope, then sort order and cost — no wasted words. It is arguably too terse rather than too long, so it loses a point for under-specification rather than verbosity.

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 list tool this covers scope, ordering, and cost, which is the minimum an agent needs to call it. However, with no output schema, the description gives no hint about what a 'report' entry contains (IDs, names, timestamps) or whether the list is truncated, leaving the agent unable to plan follow-up calls confidently.

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 burden and the baseline of 4 applies. The schema is empty and fully consistent with the description, which correctly implies no filtering or paging inputs are available.

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 noun phrase plus title makes clear this returns a collection of reports scoped to the account owning the API key, with an explicit sort order (newest first). It is distinguishable from siblings like report_get/report_status by being a collection listing, but it never explicitly names those alternatives or states that it returns summaries rather than full report payloads.

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 when-to-use guidance is given: nothing says to call this first to discover report IDs before using report_get, nor any precondition about needing existing reports. The only usage-adjacent information is the word 'Free', which hints there is no credit cost but doesn't tell the agent when this tool is the right choice over its siblings.

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?

Goes well beyond the annotations (which only say it is not read-only, is open-world and not idempotent): it discloses that the call spends money, that "credits" consumes one agency credit and requires a FULL plan, that "byok" requires an active Agent plan and specific env keys, that engines without keys are silently skipped as "skipped", that OpenAI/Anthropic/Gemini is mandatory, that refusals name the plan limit, and that runs take several minutes. This is exactly the cost/auth/failure disclosure the annotations cannot carry.

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?

Purpose comes first, then the money warning in caps, then the funding mechanics, then the polling instruction — a sensible front-loaded order with no filler sentences. The middle funding/keys passage is dense and multi-clause, which costs a point on readability.

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 9-parameter, costly, open-world mutation with no output schema, it covers cost, plan and key prerequisites, partial-engine behavior, duration and the polling path. The one real gap is that it never says what the call hands back (presumably a report id/handle that status needs), which matters precisely because there is no output schema.

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 only 44%, and the description compensates strongly on the most consequential params: it explains both funding enum values and their prerequisites, and clarifies that engines accepts a subset with keyless engines reported as skipped. It leaves plan (QUICK/FULL/DEEP), prompts, category, description and brand to the schema, and only mentions FULL in the context of credits funding rather than defining the tiers.

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?

Opens with a specific verb and resource ("Start a recomention report") and immediately specifies the mechanism: the questions are asked of every engine on the plan, several times each, with live web search. That mechanism cleanly separates it from siblings like recomention_suggest_prompts (writes questions), recomention_report_status (polling) and recomention_report_get (retrieval).

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?

Gives a hard prerequisite ("Always ask the user before calling it") and the follow-up path ("poll recomention_report_status about once a minute"), plus the conditions that select each funding mode. It does not state any when-not-to-use case or name a competing tool for a similar need, so it falls short of the explicit-alternatives bar for 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered. The description adds useful context beyond them: partial answers are available while status is incomplete ('with answers stored so far'), and the call is 'Free', which matters in a toolset where other calls likely consume credits. Polling behavior and return shape are still unstated.

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 compact sentence that front-loads the purpose and then enumerates the states. Nothing is wasted, though the list-then-clause construction reads slightly telegraphically.

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, read-only status tool with no output schema, the description supplies the key facts: the state set and the availability of partial answers. It omits what the failure payload looks like and whether the slug expires, which is a minor gap at this complexity.

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 percent and the single parameter is documented as 'The slug from a previous call.' The description adds nothing about the slug, so it neither compensates nor detracts. The baseline of 3 applies when the schema carries the parameter semantics.

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 the resource and the exact state vocabulary: 'Where a report is: PENDING, RUNNING, COMPLETE or FAILED.' That is a specific status-check purpose. It does not, however, distinguish itself from the sibling recomention_report_get, which an agent could easily confuse it with.

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 framing ('Where a report is') implies this is the right tool for polling progress, but the description never says when to call it versus recomention_report_get or reports_list, and it gives no guidance on polling cadence or when to stop. Usage is inferable but not stated.

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 readOnlyHint and openWorldHint already declared, the description adds genuinely non-obvious traits: no model call, zero cost, template-derived output, and the guarantee that the product's own name never appears in a question. It doesn't describe the returned shape or default count, so not 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?

Four short sentences, front-loaded with purpose and immediately followed by the cost/determinism guarantees and the workflow instruction. No filler, every sentence carries 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?

For a read-only, no-output-schema tool, the description covers purpose, cost profile, output constraint, and next step. The only material gap is how many questions come back by default or what the count parameter does to the result.

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 75% — domain, category, and description are documented in the schema, while count has only min/max bounds and no description. The description adds no parameter guidance beyond 'for a product', so it neither compensates for the gap nor detracts.

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?

Specific verb+resource: it suggests buyer-intent questions from fixed templates for a product. The fixed-template, no-model nature is clearly stated, which distinguishes it from report generation siblings. It doesn't explicitly name a sibling it replaces, but the pre-report positioning makes the role unambiguous.

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?

"Show them to the user to edit before starting a report" gives a clear workflow position — this runs before recomention_report_start. It gives a usage condition but no explicit exclusions or named alternatives, 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.