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

With no annotations, the description carries the full burden and it does disclose meaningful behavior: only the answer is metered at the API rate, no re-search is performed, and it works on searches started via API or MCP. It does not explain what happens if the target search is not yet completed or how the server-side wait/resume behaves beyond the schema's own note.

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 dense sentences, front-loaded with the core capability and followed by cost rationale and examples. Minor redundancy between 'without searching again' and 'Much cheaper than a new search', but nothing 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 3-parameter tool with no output schema and no annotations, the description covers purpose, prerequisites, cost model, and that answers are cited. It leaves the async wait/resume behavior and failure modes to the schema, which is a small but real gap.

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 67% (search_id and wait_seconds are documented; question is not). The example questions give a feel for acceptable question phrasing but add no format, length, or scoping guidance for the required `question` parameter, so it only marginally compensates for the gap.

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: ask a question over a completed search's corpus to get a cited answer without re-searching. Clearly distinguishes itself from the sibling `search` by emphasizing that no new search occurs.

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 the triggering condition ('completed search', 'without searching again') and concrete example questions ('what do they say about price', 'summarize the objections'), plus a cost contrast against a new search. It lacks an explicit when-not-to-use or a named alternative for the initial search case, so it falls 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?

With no annotations, the description carries the full burden and does reasonably well: it discloses cost ('Metered at the API rate'), that no new search is performed, and the shape of the output (callout + loop/promise). It omits auth/permission needs and polling semantics, though the schema's wait_seconds description partially covers the latter.

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 dense sentences, each earning its place: purpose and grounding first, then cost/wait behavior, then the steering parameter. No filler or restatement of the name.

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, and the description compensates by describing what a hook contains and that results are grounded in real comments, plus metering and wait behavior. Coverage of count semantics and rate-limit specifics is thin, but nothing critical to correct invocation 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?

Schema description coverage is 75%, so the schema already documents search_id, angle, and wait_seconds; the description's 'angle to steer (a product, a persona, a platform)' adds modest meaning over the schema's example. It adds nothing for `count`, whose schema entry has no description.

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 (write ad hooks) and resource (hooks) grounded in a named source (a completed search's quotes), and describes the output mechanics (callout from real comments plus a loop or promise). This clearly separates it from siblings like search, get_quotes, and ask.

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 establishes the precondition (needs a completed search's quotes / a search_id) and explicitly notes 'no new search,' steering an agent that needs fresh data elsewhere. It does not, however, name a direct alternative (e.g., use search first, or ask instead) for ambiguous cases.

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, but it does disclose useful behavior: this is a read-only balance lookup, searches consume the balance at the API rate, and top-ups happen off-tool at buzzsearch.ai. It omits auth requirements, currency/format of the returned balance, and any staleness or rate-limit behavior.

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 front-loaded sentences with no filler; the resource is stated first and the consumption/top-up note second. The 'top up at buzzsearch.ai' clause is mildly promotional but still operationally relevant.

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, no-output-schema tool this is close to sufficient: it covers what the value is and how it is consumed. A brief note on what the returned balance looks like would close the remaining gap.

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 for the description to disambiguate and no misleading parameter claims.

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?

Identifies a precise resource ('the user's BuzzSearch credit balance') in a noun phrase rather than a verb+resource form. An agent can tell what it returns, and the sibling list (search, get_search, ask) is clearly disjoint, though no explicit differentiation is stated.

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 or when-not guidance is given. 'Searches draw from it at the API rate' hints at a monitoring use case but never states the condition for calling it, and no alternatives are named.

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 and does reasonably well: it discloses that results are grouped by thread or video, that paging is via limit/offset, and that the call is free (cost signal). It omits auth requirements, rate limits, and any indication of what happens on an invalid or expired search_id.

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 tight sentences with the resource and its grouping stated first, followed by the filtering rationale. 'Free.' is a short standalone fragment but it carries real information, so little 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?

There is no output schema, so the description usefully covers the return shape (comment bodies grouped by thread or video, paged). For a 6-parameter read tool with no annotations this is close to complete, lacking only permission/pagination-boundary details.

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 50%, so the description must compensate, and it does: it maps sources to filtering, contains to substring matching, min_score to a threshold, and limit/offset to paging. Only search_id is left entirely to the schema, which already documents it well.

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 (raw comment bodies), the scope (behind a completed search), and the organization (grouped by thread or video, filtered and paged). It is specific enough to act on, but it never names or contrasts itself with siblings like get_quotes or get_sources, so an agent must infer the boundary.

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 states the precondition (a completed search) and gives concrete decision support: since a search reads hundreds to thousands of comments, use source/contains/min_score filters and page with limit/offset. It stops short of explicit when-not or named alternatives, 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 behavioral burden and does well: it discloses cost ('Free'), the returned payload shape (stable id, source url, dimension, engagement score, intensity 1-5), and that results are paged. It does not mention auth requirements or rate limits, which prevents 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 tight sentences, front-loaded with what the tool returns before the practical filtering advice. No filler text, though the payload-field list is slightly dense.

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 appropriately explains what each quote carries and mentions pagination, which is the essential missing information. Coverage of the non-dimension filter parameters is the only real gap for an 8-parameter tool.

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 25%, so the description must compensate. It helpfully enumerates the full dimension enum and the 1-5 intensity range, and implies the sort behavior, but says nothing about sources, contains, limit, offset, or min_intensity, leaving several parameters undocumented.

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+resource and scope: 'Verbatim customer quotes extracted by a search, filtered and paged.' An agent can distinguish this from get_comments and search by the quote resource. It stops short of explicitly naming which sibling to use instead, which keeps it from a 5.

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 one concrete usage scenario ('For ad copy, pull emotional_painpoints and customer_lingo sorted by intensity'), which is genuinely actionable. However, there is no general when-to-use guidance and no explicit contrast with get_comments or search, so the agent must infer the boundary.

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 and does disclose meaningfully: the call is free, it blocks server-side up to `wait_seconds` while the search runs, and it defaults to the latest turn. It omits auth requirements, error/not-found behavior, and any rate-limit context.

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, front-loaded with the resource and return payload, then parameter behavior. Every sentence earns its place with 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?

There is no output schema, so the description usefully names the return shape (status, answer, coverage counts, top quotes) and explains the polling/wait loop. That is sufficient for an agent to call and consume it, though error and auth context is 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 description coverage is 100%, so the schema already documents all three parameters, including the 'call again to resume' resume hint for `wait_seconds`. The description adds minor value by restating default-turn and wait semantics but nothing 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?

States a specific verb and resource ('Read a search') and enumerates what it returns (status, cited answer, coverage counts, top quotes), which separates it from the write-side `search`/`ask` siblings. It never names an alternative explicitly, so sibling differentiation is implied rather than stated.

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 explains conditional use of `turn_id` ('otherwise the latest turn is returned') and when waiting applies, but gives no guidance on when to prefer this over `list_searches`, `get_quotes`, or `get_sources`, nor any prerequisites. Usage is implied from the read-the-result framing.

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 behavioral burden. It discloses that the tool is 'Free' and what fields are returned, which is useful, but does not explain pagination defaults, permissions, or the read-only nature beyond the implied 'get/read' framing.

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 tight sentences with the core purpose and use case front-loaded. Every phrase earns its place, including the useful 'Free' note.

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 tool with no annotations, low schema coverage, and no output schema, the description covers the return contents and use case reasonably well. However, it leaves the optional limit/offset parameters and pagination behavior entirely unexplained, which is a meaningful gap 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?

Schema description coverage is only 33%: search_id is documented, but limit and offset are undocumented in both the schema and the description. The description adds no parameter-level meaning and fails to compensate for the coverage gap.

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 resource — 'the threads and videos a search read' — plus the metrics returned, so an agent knows this is a source-listing tool for a search. It does not explicitly distinguish itself from sibling tools like get_search or get_quotes beyond implying raw comments come from get_comments.

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 gives clear usage context: 'Use it to cite a thread or pick which source's raw comments to pull.' That tells the agent when to use this tool and hints at the related get_comments tool, though it does not name explicit exclusions or alternatives.

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 and it does disclose useful traits: newest-first ordering, inclusion of BuzzSearch app searches, and zero cost. However, it is silent on pagination/limit behavior and what each result entry contains, so behavioral disclosure is partial rather than complete.

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 front-loaded sentences with the core purpose stated first; the fragment 'Free.' is terse but earns its place by conveying cost routing. Slightly denser than ideal but no real waste.

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 optional-parameter list tool with no annotations and no output schema, the description covers scope, ordering, cost, and the redirection path adequately. Return-value shape is unstated, but that is a minor gap for a listing endpoint.

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 67% and the description adds nothing about limit, channel, or contains. The channel enum and the contains filter are explained in the schema itself, and limit is self-evident, so the baseline of 3 is appropriate, but the description misses an opportunity to compensate for the uncovered portions.

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 ('Recent searches by the signed-in user, newest first') with ordering and scope made explicit, and it names sibling tools (get_search, get_quotes) it should not be confused with. An agent can distinguish this list operation from the read-one operations without opening any schema.

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 a clear routing rule: to reread a past search use get_search or get_quotes rather than paying for a new one, and flags that listing is 'Free'. This gives context and an alternative, but does not fully state when this tool itself is preferred over all other search-related 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?

With no annotations, the description carries the full burden and does well: it discloses server-side waiting up to `wait_seconds`, the partial-result escape hatch (returns a search id to resume), and that the call consumes BuzzSearch credits at the API rate with the exact charge reported as `credits_charged`. It stops short of covering auth requirements, failure modes, or what happens when credits run out.

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 opening sentence front-loads the value proposition, then proceeds to mechanics, link handling, waiting, and cost in a logical order. It is somewhat dense at roughly 110 words, but each sentence carries distinct operational information rather than restating the name.

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 tool with no output schema, the description states the return shape (an answer with top quotes, or the search id), the cost field (`credits_charged`), and the resume path, which is everything an agent needs to call and follow up on it. No material gap is left for a four-parameter search tool.

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 baseline is 3, but the description adds real meaning beyond the schema: link-in-query interception behavior, the wait/resume semantics tied to `wait_seconds`, and the source scope spanning four platforms. Only `depth` and the default source set are left entirely to the schema.

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 (research what real people say across Reddit, YouTube, TikTok, Facebook) and enumerates the pipeline: discover threads, read comments, extract verbatim quotes, write a cited answer. It also names sibling tools (`get_search`, `list_searches`) so the agent can distinguish this from them without opening a schema.

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?

Explicit routing is given: a query containing a platform link reads that link's comments directly (with an optional follow-up question), and a search id should be resumed with `get_search`. It also instructs the agent to check `list_searches` first because a prior search on the same topic is free to reread — a concrete when-to-use/when-not condition.

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