ListeningMind

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

Beyond annotations, it discloses critical behavior: it is a paid call (300 Lima per 1,000 results pages), requires a key, and supports a hard cost cap via max_lima. These are essential context for an agent deciding whether to invoke it.

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 front-loaded with cost and purpose, and most sentences carry useful information. There is minor redundancy between '[Paid, about 300 Lima]' and the later charge sentence.

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 no output schema, it sufficiently describes return contents (top results, AI overview text, cited sources, domain ranking). It also covers cost, auth, and cap behavior, leaving no critical gaps 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 coverage is 100%, so the parameter definitions already carry the load. The description adds pricing context relevant to max_lima but does not add semantic detail for keywords or market beyond 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 clearly identifies the resource: top results, AI overview text, cited sources, and a domain ranking. It does not explicitly differentiate from sibling tools like 'ask', but the specific 'AI overview' retrieval focus is distinguishable.

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 provides a clear use case: 'When you need to know what AI answers say and whom they cite.' No explicit when-not-to-use or alternative tool is named, so it falls short of full 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 readOnly, idempotent, non-destructive, closed-world behavior. The description adds valuable non-annotation context: no API key needed, nothing is charged, and the output includes a stored-analysis match, preview, price, and time. It does not mention rate limits, but the key behavioral risks are covered.

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 the free/no-key hook and the core action, followed by the next step. Every sentence adds decision-relevant information 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?

Given no output schema, the description explains what the plan preview contains and clarifies billing and the follow-up call. It is nearly complete for a two-parameter tool, but the unexplained market parameter leaves a meaningful 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 description coverage is 0%, so the description must carry parameter meaning. It hints that the question can be in ko, en, or ja, but never explains the 'market' parameter or the us/jp/kr enum, leaving half the 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 action ('Turns it into a plan') and positions itself as the entry point for market questions, explicitly naming the follow-up tool place_order. This distinguishes it from siblings like estimate_cost and catalog without requiring schema inspection.

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 says 'Start here for any market question' and tells the agent to call place_order with plan_id to execute the plan. It lacks a clear 'when not to use' or comparison to alternate discovery tools, but the usage context is unambiguous.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful behavioral context that this is free and requires no key, plus the scope of data returned, though it does not mention pagination or result 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?

It is a single dense sentence with no filler, and the useful '[Free, no key]' context is front-loaded. Every phrase contributes to describing the catalog contents.

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 carry the return-value burden, and it does enumerate the datasets included. It falls short only by not clarifying how the optional 'lang' parameter affects the returned catalog.

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 0% and the single optional 'lang' parameter is undocumented in both the schema and the description. The phrase 'per market' loosely hints at localization but does not explain what 'lang' changes or whether results default to a particular language.

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 identifies the resource and enumerates its contents: raw tools and orderable products with price, markets, input, the tool-to-product map, and keyword coverage per market. It lacks an explicit action verb, but an agent can infer it is a catalog retrieval tool and it is not confused with any 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?

It only notes '[Free, no key]' and gives no guidance on when to call this instead of siblings such as keyword_info, estimate_cost, or topic_search. The agent knows what it returns but not when it is the right choice.

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 description discloses useful behavior: an e-mail is sent, disposable addresses are refused, accounts start with 100 Lima and refill 20/month on the 1st. However, that describes outbound e-mail and credit granting — a state-changing operation — while the annotations declare readOnlyHint=true, a direct conflict an agent could act on incorrectly.

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?

Semicolon-chained but front-loaded with the key fact ('[Free, no key]'), and each clause carries information: the flow, the next call, the quota, the disposable-address restriction. No filler sentences.

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 supplies what the agent most needs: what gets sent, the required verify_code follow-up, quota terms, and a rejection rule. Gaps remain around code expiry, the lang parameter, and what a successful call returns, but the core flow is 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 only 25% (only 'role' is documented), so the description must compensate. It does clarify that email is the recipient address and that company and role are optional, but 'lang' is left unexplained in both the schema and the 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?

The description states a specific verb and resource ('claim free credits / free Lima') plus the concrete mechanism (submit an e-mail, a 6-digit code is mailed to that person). It also names the mandatory follow-up tool, verify_code, so the agent can distinguish this from siblings like request_key without opening schemas.

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 conditions for use — free, no key, works inside the chat with no web page — and an explicit next step ('then call verify_code'). It does not mention when NOT to use it or name the paid/alternative credential path (request_key) as the fallback, which keeps it from 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?

Goes well beyond the annotations by disclosing cost structure (500 Lima base, 20 Lima per 1,000 keywords-only), that a key is required, that max_lima acts as a hard cap, and that an over-cap estimate returns 402 without running. It also notes the return shape (each cluster labeled from its leading keywords). This is exactly the paid-operation context annotations cannot convey.

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?

Cost information is stated twice — the leading bracket '[Paid, about 500 Lima]' and again in 'Charged for the data returned (20 Lima per 1,000 keywords...)' — and the nested parentheses make the pricing sentence hard to parse. Front-loading the cost flag is good, but the sentence structure is dense and partly redundant.

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 paid, open-world query tool with no output schema, the description covers cost, cap behavior, auth requirement, and the general return shape. It stops short of describing the cluster object structure or how many clusters typically come back, which would help an agent interpret results.

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 baseline is 3; the description adds the relationship between the output mode and price and frames max_lima as a hard cap the caller should set. Marginal but real value beyond the schema's per-field text, which already covers most of this.

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: 'Searches grouped into intent clusters' and clarifies the semantics ('how consumers frame the category', 'split a category into the sub-topics customers think in'). It does not explicitly differentiate from close siblings like intent_finder or topic_search, 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?

'When you need to split a category into the sub-topics customers think in' gives a clear triggering condition. No exclusions or named alternatives are provided, so the agent gets context but no routing guidance among the many sibling 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 read-only, idempotent, non-destructive behavior. The description adds useful context beyond that: the tool is free and requires no key, and returns quote details including stored vs new, age, ETA, and quality rule.

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 short and front-loads the free/no-key benefit, but the telegraphic fragments and parenthetical mappings make it harder to parse than necessary. It is concise but not fully clear.

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 complex 10-parameter tool with no output schema, the description covers the main estimation modes but omits enough parameter semantics and edge cases that an agent may still struggle to call it correctly in every case.

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 60%, so the schema already documents several parameters. The description adds valuable mode-specific combinations, but it leaves important parameters such as lang, scope, brand, competitors, and market usage unexplained.

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 the core action clearly: estimate or preview cost before making a paid call or placing an order. It distinguishes three estimation modes (raw tool, order, topic read), though the phrasing is terse and does not explicitly name sibling tools such as place_order.

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 conditional parameter recipes for three modes and implies use before paying, but it does not explicitly say when to prefer this over place_order or which sibling to use afterward. The guidance is implied rather than 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?

The description says cancel=true cancels a queued order, which is a mutating action, while annotations declare readOnlyHint=true. This is a direct contradiction even though the description otherwise adds useful details such as free access, key requirement, blocking behavior, and result link/report 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?

The description is compact, front-loads the key cost/access signals, then covers the order/run distinction, wait/cancel behavior, and result format in three dense sentences. Every sentence carries useful 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?

Given five parameters, no output schema, and low schema description coverage, the description does enough to explain the operational shape of the tool, including blocking, cancellation, and the result ending with a link and app report. It still leaves token/auth details and exact status values implicit.

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 40%, and the description does add meaning for wait, cancel, and token. However, token is only described as 'key needed', and 'wait=1..50' does not align with the schema minimum of 0, so the compensation is partial rather than complete.

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 and resource: get the status and, when ready, the data of an order or plan run. It distinguishes the two primary retrieval paths via order_id/status link versus run_id, so an agent can tell what the tool returns without opening the 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?

It gives clear context for using wait to block until a change and cancel to cancel a queued order, and it explains order_id/run_id selection semantics. It does not explicitly name alternatives such as place_order or state when not to use this tool, so it falls short of a full 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 declare this as read-only, idempotent, non-destructive and closed-world. The description adds useful context beyond that: it is free, requires no key, and returns a saved rather than live response.

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 a single front-loaded sentence with no waste. The key qualifiers — free, no key, saved response, before paying — all earn their 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 simple two-parameter preview tool with robust annotations and no output schema, the description covers what the tool returns and why an agent would call it. The enum details are left to the schema, which is appropriate.

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 description adds that the 'tool' parameter selects a raw tool and the 'market' scopes the sample. However, with only 50% schema description coverage and no explanation of the tool enum values, it does not fully compensate for the schema gaps.

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 returned resource: a real saved response of a raw tool for a market. It also distinguishes the tool from the paid/raw siblings by framing it as a preview 'before paying'.

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 a clear usage context: see the shape and kind of data before paying. It does not explicitly name alternatives or exclusions, but the preview-before-purchase guidance 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?

Adds substantial context the annotations do not carry: cost (~70 Lima), free re-reads if already purchased, first-test reads free, and an API key requirement. This is important because readOnlyHint=false could otherwise make an agent think the call mutates state, while the description clarifies it is a metered read. Return-shape details beyond 'evidence and volume' are still thin.

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?

Roughly three compact sentences: cost and value proposition first, then the include_relations flag, then pricing/auth conditions. Dense but every clause carries information an agent needs (price, key, facet names, optional relation expansion).

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 does say what comes back (15 elements with evidence and volume) and where relations attach. Still missing for a paid tool: what happens when max_lima is too low, whether partial results are returned, and how `types` filters the response — gaps that matter when each call costs credits.

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 25%, so the description has to compensate. It does explain include_relations=true ("adds the relations (same purchase)") and the listed 15 element names effectively enumerate the likely values for the undocumented `types` array, but it never states that the list maps to `types`, and `topic_id` is left implicit.

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 exact resource — the 15 intent elements of a stored topic — and even enumerates all 15 element types with the payload fields (evidence, volume) and the include_relations add-on. It is far more specific than a restatement of the name, though it never names a sibling like intent_finder or topic_search to differentiate the use case.

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?

"of a stored topic" implies the prerequisite (you need a topic_id from topic_search) and the pricing notes ("Free if you already bought it or for your first test reads") hint at when to call it. But there is no explicit when-to-use/when-not, and no routing versus intent_finder or get_sample despite them being obvious 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 annotations present (readOnlyHint=false, idempotent, non-destructive), the description adds substantial context beyond them: the pay-per-data pricing (20 Lima/1,000 keywords), the max_lima hard-cap semantics with 402 fallback, the key requirement, and the ranking convention. This is exactly the value-add the description should provide.

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-loads the resource and intent, then packs pricing, cap, key requirement, and ranking semantics into a few dense sentences with no filler. Every sentence 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?

No output schema exists, and the description compensates by explaining the ranking and where volumes live. For a 4-param open-world paid tool, it covers cost, auth, and return semantics well; only minor details (pagination/error behavior beyond 402) 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 baseline is 3; the description adds meaning by explaining that max_lima is a hard cap and that an over-budget estimate yields 402, and by clarifying that rank 1 = most searched with volumes surfaced via keyword_info. The remaining parameters (limit, market, keyword) 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?

States a specific verb+resource: related searches for a keyword ordered by volume, plus the intent (words people actually use around a topic). This distinguishes it conceptually from siblings like keyword_info and intent_elements, though those siblings are not named explicitly.

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 clear when-to-use framing ('when you need the words people actually use around a topic') and usage constraints (needs a key, pass max_lima as a hard cap). No explicit when-not or named alternatives, but the context is strong enough to route correctly.

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?

Beyond the annotations it discloses the pricing model (10 vs 100 Lima per 1,000 keywords), how max_lima acts as a hard cap, that exceeding the estimate returns 402 without running, and that a key is required. It also clarifies the relationship between volume_avg, volume_avg_period and monthly_volume. This is behavioral context the structured fields do not 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?

Cost and paid status are front-loaded in brackets and every sentence carries information. There is some duplication of the data_type pricing that the schema already states, which is the only 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?

With no output schema, the description still explains the main return fields and the averaging period, plus cost, cap and auth requirements for a paid lookup. It stops short of describing response structure (units for CPC, the demographics breakdown shape), a minor gap for a data-returning 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 market, keywords, max_lima and data_type are already fully documented including the cost tiers and the 402 cap behavior. The description largely restates those facts; its genuinely additive content (volume_avg vs monthly_volume) describes output, not parameters, 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 names the resource (keyword data) and the exact metrics returned: monthly volume trend, competition, CPC, and gender/age demographics for Korea. It is clearly distinguishable from siblings like estimate_cost or topic_search, though it never states its verb form or explicitly contrasts with those siblings.

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?

"When you need the size of demand, its seasonality and who is searching" gives a concrete usage condition tied to the returned metrics. It lacks any when-not guidance or named alternative (e.g., estimate_cost before committing budget), leaving that part to inference.

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 cover read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond annotations: key requirement, free allowance/wallet/cap visibility, one-hour checkout link expiry, and that the agent does not pay directly. It does not contradict the readOnlyHint because buy_pack only returns a checkout link.

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 dense sentences with no filler and front-loads the key access requirement and main result. It is appropriately sized, though the jargon 'Lima left' and packed parentheticals slightly reduce immediate 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 tool with four parameters, no output schema, and no schema descriptions, the description gives a useful high-level view of returned account data and buy_pack behavior. It remains incomplete on parameter meanings and exact output structure, leaving meaningful gaps for an agent.

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 0%, so the description must explain the four parameters. It explains buy_pack's behavior and implies that notices/orders are returned, but it does not clarify lang, the orders count parameter, or ack_notices. Most parameter semantics are left 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?

The description states the account resource and the specific outputs returned: Lima allowance, wallet, monthly cap, notices, and recent orders. It also explains buy_pack's outcome. It is clear but does not explicitly differentiate this tool from siblings such as request_key or place_order.

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 provides some context: the tool is free but requires a key, and buy_pack returns a checkout link rather than charging the agent. However, it does not explicitly say when to use this tool instead of alternatives like request_key, place_order, or get_order_result.

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 mark this as non-read-only but idempotent and open-world; the description adds material behavior beyond that: it is paid, prices differ by output mode, max_lima acts as a hard cap, calls over the estimate return 402 without running, and a key is required. That is strong cost/auth/guardrail disclosure, though it does not explain the return format or rate-limit behavior in more depth.

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 compact and front-loads the paid cost bracket before the functional description. The dense pricing clause is somewhat cryptic but every sentence carries practical 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 paid, 5-parameter search tool with no output schema, the description covers the main behavioral risks: cost, key requirement, price cap, and 402 behavior. It is reasonably complete, though it could say more about what a returned 'path' contains.

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 explains keyword, market, limit, output, and max_lima. The description reinforces max_lima as a hard cap and ties output modes to pricing, but adds little parameter meaning that is not already in 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 clearly identifies the resource: the searches made before and after a seed keyword, i.e. a search journey/path around that keyword. It is specific enough for an agent to understand the output, though it never explicitly names how it differs from siblings like cluster_finder or intent_finder.

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 phrase 'When you need to see where a journey starts and where it goes' gives an implied use case, but there is no explicit when-to-use vs. when-not-to-use guidance and no named alternatives among the many sibling tools. The cost/key notes give context but not selection 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 establish that this is a non-read-only, non-idempotent mutation, and the description adds the key behavioral facts: it is paid, spends from approved Lima, requires a key, and returns stored results immediately while builds return an order code. This is substantially more context than the annotations provide.

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 dense but front-loaded: payment status, purchase paths, return behavior, spending source, and auth requirement appear in just a few sentences. Every sentence carries operational information without 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?

For a complex paid mutation with no output schema, the description covers the critical return distinction and spending/auth constraints. It is not fully complete because several optional parameters and their behavioral effects remain undocumented, but the core invocation model is clear.

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 description adds useful semantic groupings for the core purchase paths, showing which parameters belong together for plan, topic, and product purchases. However, with only 47% schema description coverage across 15 parameters, it leaves many optional parameters (scope, brand, rebuild, competitors, callback_url, acknowledge_low_volume, lang) unexplained.

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 and resource ('buy'), and immediately distinguishes this tool as 'The one way to buy' among siblings. It also enumerates the three purchasable shapes: plan, topic, or product.

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 explicitly routes the caller by scenario: plan from ask with plan_id/approve/max_lima, topic by name with topic/market, or product with quote_id from estimate_cost or product/subject/market. It also names get_order_result as the follow-up for build orders, leaving little ambiguity about when and how to use this tool.

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 cover the safety profile (readOnly, non-destructive, closed-world), and the description adds real value beyond them: what is returned (a link and a code to show the person) and the credit/pricing model including the free tier and per-result costs. It does not say what happens after the person approves or denies, 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?

The preamble establishes cost and the sibling alternative first, then the return value, then pricing detail — a sensible front-loading order. The pricing clause is dense and semi-colon packed, but every element is decision-relevant for an agent deciding whether to call it.

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 the return value and does so (link and code). Parameters are fully schema-documented, the alternative is named, and the cost model is disclosed — nothing needed to call this correctly 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 100%, so all three parameters (agent_name, purpose, monthly_budget) are already documented, and the baseline is 3. The description adds useful context for monthly_budget by explaining the Lima pricing tiers, but says nothing about agent_name or purpose beyond what the schema 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 and resource ('Ask a person to approve an API key in a browser') plus the concrete artifact returned ('a link and a code'). It explicitly distinguishes itself from the sibling claim_free_credits, so an agent can choose between 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?

The bracketed '[Free, no key]' front-loads the condition for use, and '(use claim_free_credits to stay in the chat)' names the alternative and the exact situation that selects it. This is explicit when-to-use/when-to-use-something-else 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 cover the safety profile (readOnly, idempotent, closed-world), and the description adds real context: free with no key required, and what each topic record contains (top CEP, KBF and avoidance items). It stops short of describing result shape or size limits, but the added context is meaningful.

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 the '[Free, no key]' qualifier that matters for a paid-service family. Minor jargon (CEP, KBF, avoidance items) is used without definition, which costs a bit of clarity but not much space.

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 does the work of naming what comes back (topic plus top CEP, KBF, avoidance items) for a 6-parameter read tool. Gaps around limit/market behavior and the meaning of the domain acronyms keep it from being fully 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 only 33%, so the description carries extra burden. It clarifies q (topic words in any of three languages, empty allowed with recent), recent, and maps 'other stored results' to include_other_results, but says nothing about limit or the market enum semantics, leaving two parameters unexplained.

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: find stored topics by name across three languages, plus other stored results. It hints at the distinction from generator-style siblings (intent_finder, cluster_finder) by emphasizing 'stored', but never names an alternative explicitly.

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?

One usage mode is spelled out ('recent=true lists what was published lately'), which implies a browse-new mode versus a name-search mode. There is no guidance on when to use this versus intent_finder, cluster_finder or catalog, and no exclusions.

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 description explicitly states that on success a key is issued, free Lima are added, and the e-mail becomes a member—all clear side effects. However, the annotations declare readOnlyHint=true, which directly contradicts these stated mutations, making this a serious annotation contradiction.

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 a single, front-loaded sentence that efficiently conveys the core action and outcome. The promotional '[Free, no key]' is slightly extraneous but not harmful.

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 mutation tool with four parameters, no output schema, and an annotation contradiction, the description omits failure behavior, role/company usage, session requirements, and does not reconcile the readOnly mismatch. It is insufficient for an agent to call it safely.

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% (only email is described). The description adds that the code is 6-digit and from e-mail, but provides no meaning for role, company, or the session condition beyond the email hint, leaving half the 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?

Clearly states the specific action (verify a 6-digit code) and the immediate outcome (key issued, credits added, membership). It is distinguishable from request_key and claim_free_credits, though it does not explicitly name those siblings.

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 phrase 'Check the 6-digit code from the e-mail' implies usage after receiving a code, but there is no explicit guidance on when to use this versus alternatives like request_key or claim_free_credits, nor any prerequisites or exclusions.

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 description discloses important behavior beyond the annotations: free/no-key access, the twice-daily mapping limit, expected latency, the need to ask again with the same q, and the requirement to cite the source link. These details are consistent with readOnlyHint=false because build=true can trigger category mapping.

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 front-loaded with purpose, then operational constraints, then citation instruction. It is appropriately sized for the tool’s complexity, though the first sentence is dense and the word 'free' is repeated.

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 explains what the answer contains, how markets work, when mapping is needed, the time/rate constraints, and the required source attribution. An agent has enough information to call and use the tool 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 coverage is 67%, and the description adds useful meaning for q, build, and market: q is a plain product/category, build maps new categories with rate and time constraints, and market defaults to US with jp/kr options. The market enum values are not individually explained beyond the country abbreviations, but the overall semantic gap is small.

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 a specific resource and output: why people buy a product/category, expressed through buying situations, goals, decision criteria, thresholds, brands, and pitfalls. It is easy to distinguish from a generic keyword tool, but it does not explicitly name or differentiate itself from siblings such as intent_finder or keyword_info.

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 operational context: free with no key, mapped categories always answer, and new categories require build=true with a twice-daily limit and 2–6 minute wait. It does not explicitly compare this tool against sibling alternatives, but the conditions for using build are well explained.

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