agent-tool-finder

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

No annotations are provided, so the description carries the transparency burden. It discloses the 30-day window and that the tool is 'Free,' but does not describe the output format or authentication requirements. The read-only nature is implied by 'Get' and the stats context but not explicitly stated.

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 sentences, front-loaded with the main verb and purpose. The second sentence provides a use case and cost note, both valuable. No wasted words.

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, the description covers the key information: what is measured, the time window, and a use case. It is complete for an AI agent to decide when to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is effectively 100%. The description adds no parameter-specific semantics, but none are needed. Baseline 4 for zero parameters is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'Get' and identifies the resource as 'the agent tool market' with concrete metrics (paid x402 endpoints, MCP servers, paying users, spend). This clearly distinguishes from the sibling find_agent_tools, which searches for individual tools.

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 use case: 'deciding whether a capability is well supplied before you build it yourself.' It does not explicitly mention alternatives or when not to use, but the context is clear and actionable.

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 the one-time key return, the Bearer auth format, the enum constraint rationale (Stripe's fee), bonus percentages, and that bonus credit is never refunded. It omits failure/idempotency behavior for a payment call (e.g., whether a retry double-charges), 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?

Dense but every sentence carries information; no filler. Structure is slightly back-loaded — the critical save-the-key-ONCE warning sits mid-paragraph rather than being front-loaded, 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?

No annotations and no output schema, so the description must self-describe, and it covers mechanism, key lifecycle, spend tiers, and refund policy. Only edge-case behavior (errors, retries, expired SPT) is left undefined for a payment 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 50%, so the description must compensate. It adds real meaning for amount_usd by explaining the allowed values exist because smaller amounts lose money to Stripe's fee, and it clarifies spt's origin (Link session approval). This is more than the schema alone conveys.

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 precise verb and resource ('Add shop credits') plus the payment mechanism (Stripe Shared Payment Token). It is immediately distinguishable from the sibling credits_balance (a read) 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?

Explains the two invocation modes: no existing key → opens a new account and returns a new key; valid key present → tops up that account. It gives clear context for when each path applies, though it never names an alternative tool or states an explicit when-not-to-use.

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?

There are no annotations, so the description carries the burden of behavioral disclosure. It adds useful context about required authorization ('Bearer ck_live_… or X-Clink-Key') and cost ('Free'), but it does not describe the response format, error cases, or explicitly confirm this is a read-only operation beyond the word 'Check.'

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 sentence contains the verb, resource, scoping detail, auth mechanism, and cost. There is no filler, and the key facts are front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only balance check with no output schema, the description provides enough to invoke it correctly: what it returns conceptually, which key it applies to, and how to authenticate. It only omits formatting details of the returned balance, which is minor for this simplicity level.

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 has zero parameters and schema coverage is effectively complete, so there is no parameter ambiguity. The description appropriately focuses on the non-schema details that matter for invocation: auth headers and cost.

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 ('Check'), a specific resource ('shop-credits balance'), and the scoping context ('for the key on this connection'). It also names the relevant auth headers, making the operation identifiable and distinct from buy_credits.

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 makes the intended use unambiguous: call this to check the shop-credits balance for the current key. It does not explicitly discuss exclusions or alternatives, but with no other balance-checking sibling and a zero-parameter interface, the context is clear enough.

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

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

No annotations are provided, so the description must carry the burden of behavioral disclosure. It states the tool 'Searches 35,000+ agent-callable tools', is 'Free to use', and 'Returns what each tool does, how to call or install it, and what it costs'. However, it does not mention potential limitations, rate limits, or that it only searches (does not execute) the tools, leaving some behavioral ambiguity.

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 paragraph that opens with the core purpose and then provides supporting details. It is slightly long due to enumerating many use cases, but every sentence contributes useful information without fluff.

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 there is no output schema, the description appropriately explains what the tool returns (what each tool does, how to call/install, costs). It covers the main use cases, scope, and cost. It does not explicitly address the sibling tool or any limitations, but for a search tool of this complexity it is largely 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 description coverage is 100%, so the baseline is 3. The description adds context for the 'need' parameter with examples like 'historical lithium spodumene prices' but does not explain the meaning of each parameter in prose. It provides no additional semantic detail 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 states the tool's purpose with a specific verb ('Find') and resource ('API, data source, or MCP server'). It also differentiates from the sibling tool agent_market_stats by focusing on discovery of external tools rather than market statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit, concrete guidance on when to use the tool: 'Use it whenever you need outside data or a capability you lack' followed by numerous examples. It does not explicitly mention alternatives or exclusions (e.g., using agent_market_stats for stats), so it misses the full 'when-not-to' 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?

With no annotations provided, the description fully carries the behavioral disclosure burden. It discloses the one-call extraction behavior, returned artifacts (page count, likely_scanned flag), the no-OCR limitation, billing side effect, and the free-on-failure policy. This is unusually transparent for a tool definition.

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-loaded with the core purpose, followed by constraints, pricing, and failure policy. Every sentence adds useful information, and there is no wasted wording or repetition of schema details.

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 single-parameter tool with no output schema, the description is remarkably complete. It specifies input requirements, size limits, output highlights (page count, likely_scanned flag), OCR limitation, cost, and failure semantics. An agent has everything needed to decide whether and how to call this 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?

The input schema already documents the lone 'url' parameter as 'public http(s) URL of a PDF file,' giving 100% coverage. The description reinforces that the URL must be public and that the file is a PDF, but adds no fundamentally new parameter-level syntax or format details 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 states exactly what the tool does with a specific verb and resource: 'Convert a public PDF to plain text.' It also disambiguates itself by explicitly limiting to text-based PDFs and noting 'no OCR,' which distinguishes it from scanned-PDF tools and related text-processing 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?

Usage conditions are made explicit: the PDF must be public, under 25MB/500k chars, and text-based rather than scanned. It also explains pricing and how to obtain credentials, giving clear context for when the tool is appropriate, though it doesn't explicitly name alternative tools for other PDF scenarios.

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 the pricing model ($0.01 per call from shop credits), the free-on-failure/empty behavior, the data sources, and a facts-only scope disclaimer. It does not cover rate limits or the exact auth mechanism beyond pointing at buy_credits, but the billing and failure semantics are high-value traits not present in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the purpose, then the disclaimer, then the cost model in three tight sentences. The disclaimer sentence is somewhat long but serves a real behavioral purpose; nothing is redundant with structured fields.

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, all-optional-parameter listing tool with no output schema, the description supplies purpose, source coverage, sort order, and cost/failure behavior — enough for an agent to call it correctly. Only minor gaps remain (rate limits, return shape not needed since 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 description coverage is 100%, so q, limit and window are already documented in the schema. The description adds context (sorted by volume, hours-to-close, 24h default window) but no syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: prediction markets closing soon, with scope (Polymarket AND Kalshi), sort order (by volume) and a computed field (hours-to-close). It clearly distinguishes the resource from generic market tools but does not name or differentiate from its pm_* siblings such as pm_gaps or pm_odds.

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 implies usage (markets about to close) and routes to buy_credits for key acquisition, but gives no explicit when-to-use / when-not or alternative selection guidance versus sibling tools like pm_odds or pm_gaps. Usage is left 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?

With no annotations, the description carries the full burden and does so well: it discloses data provenance and staleness (background snapshot rebuilt every 30 minutes), billing behavior ($0.02 per call from shop credits, failed/empty calls free), the auth path (get a key via buy_credits or /buy/credits), the presence of a match_confidence signal, and an explicit facts-only disclaimer. These are exactly the traits structured fields 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?

It is on the long side, but front-loaded with the resource and its output fields, then layered with the details an agent needs (freshness, cost, disclaimer). Nearly every sentence carries information, though the list of returned fields borders on over-enumeration.

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 compensates by describing the return fields, and with no annotations it supplies the safety/cost/auth context an agent needs before calling. Nothing material for 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 100%, so q, limit, and min_gap are already documented in the schema; the description adds no syntax, units, or edge-case semantics beyond it. The unit hint ('gap in points') appears in the return-value discussion rather than for the parameters, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific operation and resource — the biggest cross-platform disagreements between Polymarket and Kalshi on the same question — and enumerates the exact payload (both questions, probabilities, gap, volumes, close dates, urls, match_confidence). This scope is inherently distinct from single-platform siblings like pm_odds or pm_search, so an agent can select it unambiguously.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied (find the largest cross-platform mispricings) and the freshness note (snapshot rebuilt every 30 minutes) plus the 'check both questions resolve on the same terms' caveat give useful operating context. However, it never explicitly states when to prefer this over pm_odds or pm_search, nor any exclusion conditions, so routing is left 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?

With no annotations, the description carries the full burden and does well: it declares the tool is a read ('Facts only'), explicitly disclaims investment advice/pricing/signal, discloses the $0.02 cost and credit mechanism, and notes that failed or empty calls are free. It does not mention rate limits or output formatting, but the coverage is strong for a read-only 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?

The description is four sentences, each earning its place: core output, disclaimer, cost/payment, and failure policy. It is front-loaded with the purpose and avoids fluff. Slightly dense with pricing and credit details, but every sentence carries operational value, so it remains efficient.

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 single-parameter tool with no output schema and no annotations, the description adequately covers what is returned, the cost, the failure behavior, and the nature of the output. It does not specify the exact output format or how 'cross-platform gap' is expressed (e.g., percentage points), but an agent has enough to call it correctly and interpret 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 description coverage is 100%, and the schema already provides an example for q ('will the fed cut rates in september'). The description reiterates 'one question' but adds no new semantic detail about the parameter (format, constraints, or normalization). Baseline 3 applies because the schema does the heavy lifting and the description adds marginal value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific resource ('Prediction market odds') and a precise scope ('a finished read for one question'), and enumerates the delivered outputs: best-matching market on Polymarket and Kalshi, implied probability, cross-platform gap, 7-day history, and a one-line summary. It implies differentiation from siblings like pm_search or pm_ticker_events through 'finished read', but does not name an alternative, so it stops short of 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?

Clear context is established: this is for a single question and returns a complete snapshot, which tells an agent when to reach for it. It also states the prerequisite of obtaining a key via buy_credits and the pricing model. However, it gives no explicit exclusions or alternatives (e.g., 'use pm_search instead for raw market lists'), lowering it below 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 discharges a meaningful part of it: it discloses a $0.01 per-call cost drawn from shop credits and that failed/empty calls are free, plus a facts-only disclaimer. It omits rate limits, key/auth details beyond 'get a key', and any pagination 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?

The what-it-returns sentence is front-loaded, followed by a short disclaimer and a compact pricing note; each block carries information. The pricing/disclaimer sentences are slightly promotional but earn their place by covering cost behavior.

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?

Without an output schema the description does the work of listing return fields, and without annotations it covers cost and failure behavior. It is nearly complete for a no-required-param read tool, though freshness semantics of the 24h/7d window and pagination 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?

Schema description coverage is 100% and all three parameters (q, limit, window) are documented in the schema, so the baseline is 3. The prose adds no syntax or format guidance beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource (prediction markets that just settled) scoped to two named venues (Polymarket AND Kalshi) and enumerates the returned fields (outcome, last price before close, volume, closed_at). This lets an agent distinguish it from closing-soon siblings like pm_closing 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?

It gives a target audience and context ('for forecasting agents grading themselves') and mentions buy_credits for obtaining a key, but it never names an alternative tool or states when to prefer pm_closing/pm_odds instead. Usage is implied rather than routed explicitly.

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

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

No annotations are provided, so the description carries the full burden. It discloses the search behavior, the returned fields, the 'facts only' nature, and importantly the cost of $0.01 per call plus the free-on-empty/failure policy. It does not mention rate limits or auth details, but the key operational behaviors 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?

The description is front-loaded with the tool's purpose, followed by useful operational details: output fields, disclaimer, cost, and credit acquisition. It is slightly longer than necessary but every sentence contributes something an agent needs to decide whether to call the tool and what to expect.

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 lists the main returned fields and explains cost and failure pricing, which is important context. For a two-parameter search tool, this covers the essential selection and invocation guidance, though it omits details about response structure or error behavior.

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 baseline is 3. The description adds a little context by saying the search is 'matching a question or topic' and lists output fields, but it does not explain q or limit beyond what the schema already says. No additional parameter-level meaning is provided.

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 the tool searches for live prediction markets from Polymarket AND Kalshi matching a question or topic, and lists the relevant output fields. It is specific enough to convey the core operation, but it does not explicitly contrast itself with sibling tools such as pm_odds or pm_ticker_events.

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 implies when to use the tool: when a user asks for live prediction markets matching a question or topic, with cross-exchange coverage. However, it does not explicitly name alternatives or state when not to use this tool, leaving the routing decision to the agent's 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?

With no annotations, the description carries the full burden and does so well: pricing and billing source (clink shop credits, get key via buy_credits or /buy/credits), free-on-empty/failed behavior, 404 when no market matches, and the facts-only/no-investment-advice disclaimer. It also describes the return shape (probability, X read, alignment verdict), which is exactly the behavioral detail an agent needs.

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?

Dense but front-loaded: the core capability leads, followed by output shape, then cost/billing, then the compliance disclaimer. The disclaimer sentence is long but arguably necessary for a finance-adjacent tool; otherwise 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?

Even without an output schema, the description explains what comes back (headline probability, crowd lean, alignment verdict) and covers cost, failure behavior, and disclaimers. An agent has everything needed to invoke it correctly and interpret 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 100% for the single required 'q' parameter, so the schema already documents it fully. The description reinforces that it takes a question/topic but adds no syntax, format, or example detail beyond the schema's own example.

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 combined verb+resource: prediction-market probability (Polymarket + Kalshi) fused with X/Twitter sentiment on the same question. It also names the concrete outputs (headline probability, crowd lean, aligned/diverges/no_clear_read verdict), which clearly differentiates it from siblings like pm_odds (odds only) and x_search (social only).

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 makes the use case clear: fetch both market probability and social sentiment in a single call, with the cost ($0.05) and the free-on-failure condition as decision inputs. It does not explicitly say when to prefer a narrower sibling such as pm_odds instead, so it stops short of full when/when-not routing.

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 provided, the description carries the full burden. It discloses the cost ($0.01 per call, free on failure/empty), clarifies it provides facts only and is not investment advice or a price target/signal. This is useful behavioral context beyond what the schema offers. It does not mention rate limits or authentication details beyond pointing to buy_credits, but the cost and disclaimer are significant.

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 efficient and well-structured. It front-loads the primary purpose and return data, then adds cost and disclaimer details in separate sentences. Every sentence adds value: purpose, data scope, disclaimer, cost, and funding path. There is no wasted wording.

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?

Despite having no output schema, the description lists the key return fields (implied probability, 24h change, volume, close date, URL), so the agent knows what to expect. It covers cost, failure behavior, and how to get credits. For a simple two-parameter tool, this is comprehensive and leaves no critical gap for an agent to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond what the schema already provides: q is a ticker or company name, limit is a number with default 20. The description restates the q semantics but adds nothing new, so it stays at baseline.

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 the verb (Open) and resource (prediction markets mentioning a US stock ticker or company), explicitly covering both Polymarket and Kalshi in one call. It lists the exact data returned (implied probability, 24h change, volume, close date, URL), which distinguishes it from siblings like pm_odds or pm_search that likely serve different scopes. This is a specific and unambiguous purpose.

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 implies when to use it: for prediction markets on US stocks, combining two platforms. It provides context on how to fund usage (buy_credits or /buy/credits) and states the cost model. However, it does not explicitly mention alternatives or when NOT to use this tool versus pm_odds or pm_search. The usage guidance is clear but lacks explicit 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?

With no annotations, the description carries the full behavioral burden and does so richly: 404/no charge on no change, cursor always returned, $0.02 per call, payment source, failed/empty free, and a clear non-advice disclaimer.

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 purpose is front-loaded and the paragraph is dense but mostly earns its place with output, billing, and safety details. It could be split for scanability, but there is little pure 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 annotations and no output schema, the description compensates by listing the return fields, error semantics, cost model, and usage context. An agent has enough information to invoke it correctly and interpret empty 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 description coverage is 100%, so the schema already documents q, ids, cursor, and min_move. The description adds only the 'up to 20 market ids' limit and otherwise repeats what the schema provides, making 3 the appropriate baseline.

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: 'Prediction market watch/monitor' with the exact scope 'only what changed since your last check.' It clearly distinguishes itself from search or odds siblings by returning deltas, moved flags, newly-listed markets, and a cursor.

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?

Explains when to use it: after a previous check, to monitor changes via up to 20 ids or a topic. It does not explicitly compare against every sibling (e.g., pm_odds, pm_gaps), but the context is clear enough for an agent to select 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?

With no annotations, the description carries the behavioral burden well: it discloses that clink reads requests same day, buildable asks ship as pay-per-call x402 endpoints usually within a week, and it returns a request id and status URL. It also explains the notify option and the decline path.

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 sentences, front-loaded with purpose and usage, then process and return details. Every sentence adds 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?

Complete for a request-submission tool: it covers when to use it, what happens after submission, expected turnaround, return values, and notification. No output schema exists, but the return shape is described sufficiently.

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 input schema already documents all three parameters. The description only reiterates the notify parameter and adds no extra meaning for want or budget_usd, making the baseline 3 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 specific verb and resource: ask clink's shop to BUILD a tool or data source that nobody sells yet. It explicitly differentiates from find_agent_tools by saying to use it right after that sibling comes back unsatisfied.

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 precise condition: use this right after find_agent_tools comes back unsatisfied. It names the alternative and leaves no ambiguity about when this tool is appropriate.

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

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

No annotations exist, so the description carries the full transparency burden; it discloses that output is factual, not advice, and explains the $0.01 cost, the credits payment route, and that failed/empty calls are free. It does not mention rate limits or response volume, but for a read-only data pull these are adequately 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?

The description is moderately long but every sentence contributes: scope, field list, source, disclaimer, cost, failure policy. It front-loads the core purpose and keeps caveats after the main 'what it does' statement.

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 data tool with 3 parameters and no output schema, this description is complete: it names the returned fields, the cost model, the credit requirement, and the free-on-failure behavior. It does not define filing code meanings or date formats, but that is minor.

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%, and the description adds only the field list implied by the tool, not new detail on days/limit semantics. The ticker example matches the schema description. With the schema already documenting the parameters, a baseline 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 the specific resource: SEC Form 4 insider trading for one US stock ticker, enumerating the delivered fields. This differentiates it from sibling market tools like ticker_brief or pm_ticker_events without needing to open their 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?

The description implies the use case (single US ticker, window-based insider filings) but never names alternatives or gives when-not-to-use guidance. It includes a useful disclaimer and cost, but not a routing rule like 'use pm_ticker_events for broad events'.

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 deliver real behavioral context: cost (free), turnaround (read the same day), and outcome (real bugs get fixed and the reporter is told). It stops short of covering rate limits, auth requirements, or what the immediate response looks like, but the disclosure of SLA and cost is genuinely useful.

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 carries purpose, scope, the alternative tool, the SLA, the outcome, and the price with zero filler. Nothing could be cut without losing routing or expectation-setting 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 no-output-schema feedback tool, the description tells the agent what happens after submission and how it relates to its sibling. With 88% schema coverage the parameter side is handled by the schema, so the remaining gap is minor.

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 88%, so the schema already documents route, notify, wanted, receipt_id, request_url, and tx_or_buyer in detail. The description adds the framing that this is 'for a call you already made', which explains why the linking params exist, but it does not add syntax or format meaning 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?

States a specific verb (Report) plus the exact resource and concrete complaint types (bug, missing feature, wrong data, slow call), and names the sibling request_agent_tool as the thing it is not. An agent can distinguish it from every other tool in the list 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?

Gives both sides of the routing decision: use this for a call you already made, and use request_agent_tool for a new capability request. The condition that selects the alternative is stated explicitly rather than left 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?

With no annotations, the description carries the behavioral disclosure burden. It goes beyond the schema by disclosing that sections fail independently, costs $0.04 per call, failed or empty calls are free, and it is facts-only with no investment advice. This is substantial transparency, though it omits details like rate limits or response shape.

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 well-structured, front-loading the core purpose before adding failure semantics, disclaimers, and pricing. Every sentence contributes useful information, though the combined clauses make it slightly long.

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 and no annotations, the description covers the key behavioral and commercial details: data sections, partial-failure behavior, cost, credit payment, and a free-failure guarantee. It could be more explicit about how results are returned, but an agent has enough context to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents the single ticker parameter with an example. The description adds 'US stock' context but no further format or syntax guidance beyond what the schema provides, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific resource and action: a one-call US stock ticker brief that bundles X/Twitter activity, prediction markets, SEC Form 4 insider activity, and the latest 8-K. It clearly differentiates from sibling tools like x_digest, sec_insider, and pm_odds by emphasizing the bundled one-call nature.

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 implies usage: use this when you want multiple related data categories in one call rather than calling separate tools. It does not explicitly name alternatives or state when not to use it, but the 'one-call ... bundled' framing provides clear context for choosing it over the individual 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?

With no annotations, the description carries full burden and does well: it discloses cost ($0.02 from clink shop credits), the auth path (get a key with buy_credits or /buy/credits), and the free-on-failure/404 policy. It also lists the component data sources and the shape of the AI summary. No rate limits or latency, 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?

Front-loaded with the core action and result set, then the not-advice disclaimer, then cost/auth/free-call mechanics. Dense but every clause conveys distinct information; the parenthetical source list is the only slightly heavy element.

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 enumerating the returned fact categories and the AI summary fields (level, confidence, flags). Cost, auth, and failure behavior are covered. Missing only operational details like latency or rate limits, which are minor.

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% and there is only one parameter, so the schema already fully documents 'address' as a 0x-prefixed Base token contract. The description adds only the implied input source ('send a contract address') and no syntactic detail beyond the schema — baseline 3.

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: send a Base token contract address, receive honeypot/tax/ownership facts, DEX price/liquidity, holder count, social chatter, and an AI risk summary. The enumerated data sources (GoPlus, DexScreener, on-chain, X) make the tool unmistakable among the pm_/x_/sec_ 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?

It implies the use case (risk assessment on a Base token) and states what it explicitly is not (not investment advice, no buy/sell signal), which is a useful boundary. But it never says when to prefer it over alternatives or what precondition must hold — no guidance on how to obtain the address or when the tool is the wrong 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It exceeds this by revealing source auto-detection, return format (JSON with detected source + translation), cost ($0.01), payment source (clink's shop credits), and the free call policy for failures. This is comprehensive and honest, with no contradictions.

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 concise, with three sentences covering purpose, constraints, output, cost, and payment. It front-loads the core function and provides essential operational details without redundancy. It could be slightly tighter, but each sentence earns its place by conveying necessary information for correct invocation.

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 translation tool with only 3 parameters and no output schema, the description is complete: it covers input limits, optional vs required params, return format, cost, and error handling (free on failure). An agent has all necessary information to decide whether and how to call this tool, including payment prerequisites. Nothing critical 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 coverage is 100%, providing baseline 3. The description adds value beyond the schema: it specifies the character limit, clarifies that source_lang is optional and auto-detected when omitted, and gives example target language formats ('English', 'es'). This enhances the agent's understanding of parameter usage and practical constraints.

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 explicitly states the tool translates text, with a clear resource ('text') and verb ('translate'), and includes constraints (2,000 chars, any language pair, auto-detection). It is unambiguously distinct from all sibling tools, which are market/agent tools with no translation overlap.

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 clearly communicates when to use the tool (for any translation need) and provides practical usage context: length limit, cost per call, and how to obtain credits via buy_credits. While it does not explicitly contrast with alternatives, none of the sibling tools offer translation, so uniqueness is implicit. It could have stated 'use this for translation' more directly, but the intent 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 burden. It discloses the internal pipeline (neural search + page read + AI synthesis), the output contents (quotes, URLs, confidence), the cost per call, and the free-failure policy. It does not mention rate limits or explicit read-only status, but the absence of destructive implications plus the cost details are sufficient for this type of 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?

The description is longer than ideal but every sentence earns its place: purpose is front-loaded, followed by scope options, cost, and failure policy. No redundant phrasing; the 'Not a raw SERP' and cost details are valuable differentiators.

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 explains what the answer contains, its limitations, and cost. It covers all necessary aspects for an agent to decide and invoke correctly, though it could benefit from an example or explicit alternative-tool routing. Overall, it is well-rounded given the schema's completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all parameters. The description adds minimal extra nuance (e.g., 'up to 5 domains', default for max_sources is in schema). It does not introduce any parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource ('ask a question, get a short answer') and explicitly contrasts itself with a raw SERP, distinguishing it from sibling search tools. It also enumerates what the response includes (verbatim quotes, source URLs, confidence), leaving no ambiguity about the tool's core function.

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 when to use this tool (for a cited, synthesized answer rather than raw results) and provides clear constraints like date scoping and domain limits. It does not explicitly name alternative sibling tools or state when NOT to use it, but the 'Not a raw SERP' warning and cost model give practical context for selection.

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 provides key behavioral details: cost per call, payment via clink's shop credits, a link to obtain a key, and that failed/empty calls are free. This goes beyond a bare description and discloses failure and monetization behavior, though it does not mention rate limits or side effects (likely none).

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 concise and well-structured: purpose is front-loaded, followed by the query compatibility note, then cost/payment details, and a clear failure policy. Each sentence serves a purpose 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 or annotations, the description covers the essential aspects: what the tool returns (summarized sentiment, themes, accounts, posts), query syntax compatibility, cost, payment mechanics, and the free-on-failure policy. It lacks detailed output formatting or rate limits, but is reasonably complete for a single-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 100% with an example, so the baseline is 3. The description adds 'Same query syntax as x_search,' which is a useful cross-reference that tells an agent the query parameter behaves exactly like the sibling tool. This is a genuine semantic addition, but it doesn't deeply extend the schema's own 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 clearly states the tool provides a trend digest combining live tweet search with an AI-written summary covering sentiment, key themes, driving accounts, and notable posts. It references 'Same query syntax as x_search,' which distinguishes it from its sibling search tool by focusing on the analytical digest rather than raw results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage through 'trend digest' vs. a plain search, and provides a cross-reference to x_search for query syntax. However, it does not explicitly state when to choose this tool over alternatives or when not to use it. The cost and credit information is helpful context but not a substitution for explicit alternative routing.

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 the cost ($0.20 per call), the payment source (clink shop credits, with buy_credits as the key path), and the refund policy ('a failed or empty call is free'). It also reveals the internal scope (up to 4 pages, top 10-15 enriched). It doesn't describe the return shape or any rate limits, keeping it just shy 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?

Front-loaded with the core capability in the first sentence, followed by use cases and cost. Dense but every clause carries information; only the payment detail is slightly verbose for a description field.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must convey returns, and it does via 'clusters them with a one-line why-they-match each' alongside the website/emails/LinkedIn/GitHub enrichment. Cost and payment path are covered, though the exact response structure and any auth/key requirement beyond buy_credits remain 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 coverage is 100%, so both parameters are already documented, and the baseline is 3. The description loosely implies what 'max' controls by mentioning 'top 10-15' enriched people, but it doesn't clarify the enrichment scale or query syntax beyond what the schema's own examples provide.

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 chain and resource: 'searches up to 4 pages, finds the PEOPLE behind the posts, enriches the top 10-15 with their own website... and clusters them'. This clearly distinguishes it from siblings like x_search, x_person, and x_profile by describing the full search -> profile -> contact pipeline in one 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?

Gives concrete use cases ('Recruiting, B2B prospecting, cofounder/investor search') and explains the credit/payment mechanics, which is genuine usage context. It stops short of explicitly contrasting when to prefer this over x_search or x_person, so it doesn't reach the top tier.

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 fully carries the behavioral disclosure burden. It covers deduplication, newest-first ordering, per-handle counts, the since-cursor semantics, the 2-50 handle range, the missing from:-OR-splitting capability, the cost per call, and the fact that failed or empty calls are free.

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 front-loads the behavioral core in the first phrase and then packs the limitation, cost, and failure policy into a few compact sentences. There is no filler, no restatement of schema fields, and every sentence contributes useful selection or invocation guidance.

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 straightforward tool with three parameters and no output schema, the description supplies all key operational details: batch size, ordering and dedupe behavior, per-handle counts, incremental cursor, pricing, and failure-cost policy. Nothing essential for selecting or invoking the tool 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 coverage is 100%, so the baseline is 3, but the description adds meaningful constraints not present in the schema: the 2-50 handle count and the purpose of the since cursor as an only-what's-new incremental token. This helps an agent construct valid parameter values.

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 core function: a batch X/Twitter watchlist that fetches combined recent tweets for 2-50 handles, returned newest first and deduped with per-handle counts and a since-cursor. It lacks a crisp verb phrase like 'fetch' or 'list', and the 'No from:-OR-splitting' note only weakly differentiates it from sibling tools like x_search.

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 a clear use case—multiple handles in one call for watchlist-style monitoring—and gives one explicit exclusion: it does not support from:-OR splitting. It also tells the agent how to get credits via buy_credits or /buy/credits, but it does not name sibling alternatives for single-handle or search scenarios.

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 provided, the description carries the full behavioral burden. It discloses the $0.15 cost, that it's paid from shop credits, that failed/empty calls are free, and lists the output contents (contact routes, non-LLM stats). It does not explicitly state that the tool is read-only, but a lookup tool by nature does not mutate; the cost and output disclosures go beyond minimal expectations.

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, well-structured paragraph that front-loads the core purpose ('enriched PERSON CARD') and then lists key outputs with a dash-separated list, followed by cost and failure behavior. It is slightly longer than necessary but every sentence adds value—no filler. The structure aids scanning.

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 single-parameter lookup tool with no output schema, the description covers what the tool returns, its cost, how to fund it, and the free-on-failure policy. It does not detail the exact output format or data types, but without an output schema that is not strictly required. An agent has enough to call it correctly and interpret 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?

There is only one parameter 'username' with a clear schema description ('X handle, e.g. naval'). Schema coverage is 100%, so the schema already documents the parameter. The tool description adds no extra semantics about format, validation, or edge cases beyond the schema, so it sits at the baseline of 3.

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 'lookup' with a clear resource ('X/Twitter person'), and enumerates the enriched data delivered (name, role, company, topics, contact routes, stats). It clearly distinguishes itself from siblings like x_profile (which likely returns a simpler profile) and x_search (which searches tweets), by emphasizing the 'enriched PERSON CARD for a lead/recruiting/sales agent'.

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 targets a lead/recruiting/sales agent use case and explains cost and how to fund it (buy_credits), plus the free-on-failure guarantee. It doesn't explicitly name alternatives or when-not-to-use, but the purpose is specific enough that an agent can infer when to choose it over x_profile or x_search. A small gap is the absence of an explicit exclusion, hence a 4.

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 provided, the description carries the full burden. It usefully discloses pricing ($0.02 per call), the payment mechanism (clink shop credits), how to obtain a key, and the failure policy (failed or empty calls are free). This is meaningful behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences: the first states the purpose and return fields, the second covers cost and failure policy. No filler, and the most important purpose information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter lookup tool, the description is largely complete: it lists all returned data fields, explains cost and failure behavior, and the schema covers the required input. It could optionally mention whether to include the '@' prefix, but the example makes this 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 single parameter 'username' is already fully documented in the schema with a clear example ('elonmusk'). The description adds little param-specific meaning beyond saying 'one handle', so the baseline 3 applies due to high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'X/Twitter profile lookup'. It enumerates the exact fields returned, which clearly distinguishes it from sibling tools like x_search and x_digest that cover posts or market-specific 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?

The description implies when to use the tool — when you need profile metadata for a single handle — but it does not explicitly state when to prefer it over alternatives like x_search. It also provides practical prerequisite information about credits and keys, but no explicit exclusion 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?

With no annotations, the description carries the behavioral burden and does well: it discloses cost per call, how payment works, that failed/empty calls are free, and what the response contains. It omits minor details like rate limits or auth key handling, but the key behaviors 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?

Three sentences, each earning its place: purpose and syntax, response shape, and cost/failure semantics. The text is front-loaded with the main action and free of 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 one-parameter tool with no output schema, the description covers everything needed: how to form queries, what fields to expect, per-call cost, and the free-on-failure condition. The agent can invoke it correctly without more context.

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 schema already describes the single query parameter with an example, and coverage is 100%. The description adds valuable semantics by listing the exact advanced operators an agent can use, enriching the bare word 'query' with concrete syntax.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Live X/Twitter search for AI agents.' It further disambiguates by listing supported search syntax and result fields, distinguishing it from siblings like x_profile or x_digest.

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 establishes a clear use case: live X/Twitter search with advanced query syntax, so an agent knows when to call it for fresh posts. It does not explicitly name alternatives or state when not to use it, but the context is clear enough.

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

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

With no annotations, the description carries the full burden. It discloses that it is facts-only, not investment advice, and explicitly states the cost ($0.02 per call) and that failed/empty calls are free. It also reveals the comparison behavior (vs prior window) and the keyword topic flags. It does not mention rate limits or auth requirements beyond the payment key, but the cost and failure disclosure is strong.

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 well-structured: it front-loads the core function, then lists outputs, then adds caveats and cost. Every sentence earns its place, and the cost/failure note is valuable for an agent deciding whether to invoke.

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 does a good job of explaining what the agent will get: post volume, top posts, active accounts, and topic flags. It also covers cost and failure semantics. It lacks explicit return format details (e.g., JSON shape), but the enumerated outputs are sufficient for an agent to understand the tool's purpose. The absence of an output schema is partially compensated by the detailed output list.

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 both parameters. The description adds context for the ticker parameter by saying 'one US stock ticker' and implies the window parameter via 'prior window', but it does not add syntax details beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('X/Twitter activity for one US stock ticker') and enumerates the exact outputs: post volume vs prior window, top posts, most active accounts, and keyword topic flags. It clearly distinguishes itself from siblings like x_search, x_digest, and x_profile by focusing on a single ticker's activity summary rather than general search or profile 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?

The description implies when to use this tool: when you need X/Twitter activity for a single US stock ticker, including volume comparisons and topic flags. It does not explicitly name alternatives or exclusions, but the sibling list and the specific scope ('one US stock ticker') provide clear context. It also states cost and failure behavior, which helps an agent decide whether to call it.

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