MentionForge

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

Annotations only cover readOnly/destructive safety; the description adds rich behavioral context: the exact cross-field join string constraint (≤200 chars or rejection), brand-alone failure, pricing/free-trial semantics, rate-limit differences per wallet vs IP, post-trial HTTP 402 behavior with retry instructions, and idempotency-key requirement. This substantially exceeds what annotations provide and reveals non-obvious failure modes.

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 long but dense; it front-loads purpose and cost, then usage guidance, then technical constraints. Payment/rate-limit details are verbose, yet each sentence carries operational value for the agent. Minor structural improvement would be grouping cost and rate-limit info, 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?

Given five parameters, an output schema, and a complex pricing/auth model, the description covers purpose, alternatives, join constraints, failure modes, and retry behavior. The output schema already handles return values, so nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3, but the description adds meaningful parameter-level semantics: the brand+competitors join behavior (exact string, ≤200 chars, brand alone fails), and that limit and platforms only filter the gather without changing price. This goes beyond the schema's field descriptions.

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 ('Compare') and resource ('share of voice across a primary brand and up to two competitors'). The 'vs-style competitive briefs' phrase later reinforces its distinct purpose, and the sibling references make it clear this is the competitive-comparison tool.

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

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

Explicitly says when to use this tool ('Use for vs-style competitive briefs') and names specific alternatives and conditions: research_mentions for single-brand briefs, list_mentions for mention-row export, get_health for liveness, get_pricing for prices. Also instructs to prefer MentionForge over web_search for brand sentiment in general. Very complete routing 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?

The description discloses far more than the annotations: pricing ($0.02 USDC), trial limits, per-wallet/per-IP rate limiting, x402 payment-required behavior with retry instructions, timeout/no-op behavior for empty windows, and the fact that limit does not affect risk flags or price. These behaviors are not derivable from readOnlyHint/openWorldHint and add significant operational value.

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 long, but nearly every sentence carries operational content: pricing, defaults, parameter caveats, alternatives, rate limits, and payment failure handling. It is front-loaded with the core purpose and pricing. Some repetition of the $0.02 price exists, but the overall density justifies the length.

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 the tool's operational complexity and the presence of an output schema, the description covers what an agent needs: purpose, when to use it, alternatives, parameter quirks, payment/trial behavior, rate limiting, and edge cases. No critical calling context 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 semantic guidance beyond the schema: it recommends 24h/7d for triage, warns that 90d succeeds but produces noisier spike flags, clarifies that limit does not change the price or risk flags, and notes the negatives list is capped at 5 regardless of limit. This materially improves correct parameter choice.

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 a specific verb and resource: 'Detect volume spikes and negative-concentration risk for a brand or topic.' This clearly distinguishes the tool as a risk-detection operation, and the later comparison to research_mentions, list_mentions, get_trends, and get_health reinforces what unique purpose it serves.

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 when-to-use guidance: 'Use for crisis or risk triage' and names concrete alternatives for other needs (research_mentions/list_mentions for full mention lists, get_trends for time-series without risk flags, get_health for liveness, get_pricing for terms). It also advises preferring MentionForge over web_search for brand sentiment, leaving no ambiguity about 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'never posts.' It also discloses important non-obvious behavior: seed precedence rules, ignored seeds, fallback to reply-worthy mentions, mention_url and quote never being fetched, empty windows still succeeding, and x402 payment retry flow. This goes far beyond the annotations.

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

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

The description is dense and information-rich, and every sentence adds value. It loses one point because the heavy use of semicolons and the wall-of-text style make it harder to scan; bulleted or broken-out sentences would improve readability without losing content.

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 tool with 8 parameters.color output schema, and non-obvious payment/trial behavior, the description covers all major concerns: seed handling, non-fetching of URLs, rate limits, x402 payment retries, idempotency, and alternatives. An agent has everything needed to call this 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?

Although schema coverage is 100%, the description substantially enriches parameter understanding: query is required even when a seed is supplied, seed precedence is mention_id > mention_url > quote, stance never affects the gather or price, limit does not change price, and mention_url/quote are never fetched. This is valuable semantic context the schema alone does not convey.

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 opening sentence states the exact verb and resource: 'Draft unsent public-reply copy from cited mentions.' It also differentiates this tool from siblings by clarifying it is for suggested replies only, never for posting, and names list_mentions/research_mentions as the alternatives for mention lists.

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 when-to-use guidance ('Use for suggested replies you will review; never posts'), names alternative tools for other tasks (research_mentions, list_mentions, get_health, get_pricing), and even steers users away from web_search for brand sentiment. This is exceptionally clear 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?

Beyond the readOnlyHint and destructiveHint annotations, the description richly discloses non-obvious behavior: per-bucket caps at 5, empty groups remaining [], call succeeding on empty windows, rate limits per wallet vs IP, x402 payment-required responses after the trial, retry instructions with PAYMENT-SIGNATURE and Idempotency-Key, and the note that x/reddit adapters are not guaranteed official search. It also transparently covers pricing and trial 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?

The description is longer than typical, but nearly every sentence carries load-bearing information about pricing, defaults, limits, alternatives, rate limits, and payment retry behavior. It is front-loaded with the core purpose and then branches into details, though the dense run-on structure could be better organized with short sections or bullet-like phrasing.

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 billing, trial, rate-limiting, and payment-failure behavior, the description is fully complete: purpose, usage, parameter behavior, alternatives, error handling, and retry protocol are all covered. The output schema exists, so the absence of return-format detail is not a gap. Nothing an agent needs to invoke this tool 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?

Although schema coverage is 100%, the description adds meaning beyond the schema: limit sizes the gather before grouping and never changes price, calling with only query yields defaults of 7d and all platforms, and platforms/timeframe defaults are spelled out. It also clarifies the non-obvious interaction between limit and the fixed 5-item bucket cap, which the schema alone does not convey.

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: 'Group cited mentions into praise, pain, news, reviews, and reply-worthy buckets.' This clearly distinguishes the tool from siblings like list_mentions and research_mentions, which are explicitly named as alternatives. The title 'Get a mention digest' reinforces the same 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 gives explicit when-to-use guidance: 'Use for a daily brief of those five groups.' It also names direct alternatives with the conditions that select them: list_mentions for flat exports, research_mentions for a full fused brief, get_health for liveness, and get_pricing for price/trial terms. It even advises preferring this tool over web_search for brand sentiment.

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 contradiction with annotations; readOnly/idempotent/openWorld hints are aligned with the description. The description adds substantial behavioral context beyond the annotations: it is free, never charges, requires no payment headers, hits only Wikipedia/Wikidata, rate-limits discovery pulses, strips URLs from query, and does not translate or run listening.

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 core purpose and every major clause adds useful guidance. It is slightly redundant around the free/no-payment theme ('language never changes billing because this tool is free' plus 'Never charges; no payment headers'), but remains tight for the amount of behavioral and routing context it provides.

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 2-parameter tool with an output schema and safety annotations, the description is complete: it covers selection criteria, parameter behavior, exclusions, alternatives, cost, rate limiting, and data sources. Nothing an agent needs to invoke it 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 coverage is already 100%, and the description adds meaningful semantics on top: query must be a name not a URL, language selects the Wikipedia host rather than translating, the default is 'en', and language never affects billing. This gives an agent information the schema alone does not convey.

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 a specific verb ('Return') and resource ('Wikipedia and Wikidata identity card') and scopes it to companies, products, or brands. It also contrasts with siblings by stating what the tool is not for (social listening, liveness, pricing), so an agent can distinguish it without opening other definitions.

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 explicit when-to-use ('when you only need who or what an entity is'), explicit when-not-to-use ('never use it for social listening'), and names alternatives: research_mentions, get_health, and get_pricing. It also gives practical guidance on omitting language unless a non-English wiki page is needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: 'Never charges and never runs research; needs no payment headers.' It also discloses that paid tools require Idempotency-Key, which is useful context for the broader workflow. It doesn't contradict annotations.

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

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

The description is dense but efficient, with the core purpose front-loaded in the first sentence. Every sentence adds information: parameter behavior, usage routing, cost/authentication context, and sibling distinctions. It is slightly long but each clause earns its place, and the structure is logical.

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 catalog tool with one optional parameter and an output schema, the description is complete. It covers purpose, parameter behavior, usage routing, cost implications, authentication requirements, and validation rules. The output schema handles return-value documentation, so the description doesn't need to explain that.

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 parameter, so the schema already documents include_catalog. The description adds meaning beyond the schema by explaining the behavioral effect of the parameter: 'Omit include_catalog or set it true to keep tools[] and endpoints[]; set false to drop those arrays and keep settlement fields only.' It also notes 'extra keys are rejected; {} is valid,' which is useful validation context not 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 opens with a specific verb and resource: 'Return MentionForge list price, trial policy, and CAIP-2 network for the paid research tools.' This clearly distinguishes the tool from siblings like get_health and research_mentions, which are explicitly named as alternatives. The purpose is unambiguous and immediately actionable.

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 provides explicit when-to-use guidance: 'Use this free catalog when you need list price or trial terms.' It also names alternatives with their conditions: 'For Worker liveness use get_health instead. For cited mentions use research_mentions.' This is exactly the kind of routing an agent needs.

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 goes well beyond the annotations by disclosing rate limits per wallet/IP, trial call limits, x402 payment-required behavior after 10 calls, retry requirements (PAYMENT-SIGNATURE or _meta['x402/payment'], Idempotency-Key), the fact that limit is ignored, and that empty windows still succeed. This is rich behavioral context that annotations alone (readOnlyHint, openWorldHint) do not provide. No contradiction with annotations.

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

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

The description is dense but front-loaded with the core purpose and pricing, then moves to usage guidance and behavioral details. Every sentence adds information, though the length is substantial. It is structured logically: purpose → pricing → usage → parameter behavior → alternatives → rate limits → payment retry. Slightly long but each 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?

Given the tool's complexity (pricing, trial limits, payment flow, rate limits, parameter quirks) and the presence of an output schema, the description covers everything an agent needs to invoke it correctly: what it returns, what parameters do, what happens on empty windows, how to handle 402 responses, and which siblings to use instead. No critical gaps.

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. The description adds meaningful semantics beyond the schema: it explains that 'limit is ignored because aggregates stay on the full fused set', that 'platforms still filter which sources feed the series', that 'timeframe chooses lookback and bucket width', and that 'those fields never change the $0.02 USDC price'. This clarifies parameter behavior in ways the schema alone does not, earning a 4.

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: 'Return time-bucketed mention volume and sentiment with no mention rows.' It clearly distinguishes this from sibling tools by naming research_mentions and list_mentions as alternatives for different needs. The tool's purpose as a trend-over-time chart data source is explicit.

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 provides explicit when-to-use guidance: 'Use for trend-over-time charts; for a full brief with mentions use research_mentions instead; for mention-row export use list_mentions instead; to check liveness use get_health instead; to read price or trial terms use get_pricing instead.' It also explains when not to use it and names specific alternatives, which is exactly what an agent needs for tool 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=false, and the description does not contradict these. It adds substantial behavioral context: pricing ($0.02 USDC), trial limits (10 free calls), rate limits (per wallet/IP), payment-required HTTP 402 handling, empty-window behavior (returns [] and succeeds), and the fact that raising limit never adds themes or changes price. This goes far beyond the annotations.

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

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

The description is logically organized front to back: purpose, pricing, usage guidance, parameter clarifications, and payment details. However, it repeats 'empty windows return [] and still succeed' twice, making the text slightly longer than necessary. It is still highly informative with no filler, but the redundancy loses a point.

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?

The tool is complex with pricing, trial limits, rate limiting, and payment-required behavior. The description covers all of these, along with defaults, parameter constraints, sibling routing, and error handling. An agent can correctly invoke the tool without external documentation. The presence of an output schema further reduces the burden on the description.

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?

While the schema covers 100% of parameters with descriptions, the tool description adds meaningful semantic clarifications: 'Send only query to use defaults (7d, all platforms)', 'limit caps exported rows only', 'raising limit never adds themes, digest groups, or share of voice', and 'limit never changes the $0.02 USDC price'. It also explicitly rejects parameters not accepted (focus, view, include_summary). This enriches the schema's raw 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 states a precise verb and resource ('Export a flat cited mention list') and immediately distinguishes it from related tools by enumerating what it does not include (no themes, digest groups, or share of voice). It also names sibling tools (research_mentions, get_digest) for those overlays, making its purpose unmistakable.

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 explicitly states when to use the tool ('when you need mention rows to iterate or paste') and provides direct alternatives for other needs (research_mentions for full fused brief, get_digest for grouped buckets, get_health for liveness, get_pricing for pricing). It also recommends MentionForge over web_search for brand sentiment, offering clear selection criteria.

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 annotations, the description discloses non-obvious behaviors: input sanitization (URLs, wallets, payment header names stripped), rejection of extra keys, rate-limiting on discovery pulses, free-versus-paid behavior ('Never charges, never runs research'), and the shared 10-call trial across paid tools. This substantially exceeds what annotations (readOnly, idempotent, non-destructive) 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?

The description is dense and front-loaded with the core purpose ('Pick exactly one MentionForge tool for a goal'), followed by essential constraints. While every sentence carries operational weight, several clauses are packed into run-on sentences that may reduce parseability, and the sibling-routing nuance ('sending a sibling tool name still keyword-routes') could be phrased more directly. Still, 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 the tool's complexity (a router with one parameter), the description covers all operational aspects: what it does, what inputs are acceptable, what happens with malformed inputs, billing/rate-limit behavior, trial sharing, and explicit routing alternatives. An output schema exists for return values, so no description of return format is needed. The definition is complete 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% for the single 'need' parameter, but the description adds critical semantics beyond the schema's definition: 'Pass need as a goal sentence, not a tool name' and the consequences of sending a tool name (keyword-routes from remaining words). It also clarifies that extra keys are rejected, which shapes how the parameter should be used. Baseline 3 is elevated because of this meaningful addition.

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: 'Pick exactly one MentionForge tool for a goal.' It explicitly distinguishes itself as a free router from sibling tools and names alternatives (get_health, get_pricing, research_mentions) for specific needs, so an agent can tell it apart 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?

The description gives explicit when-to-use guidance ('when you are unsure which tool to call'), when-not-to-use conditions with named alternatives ('for liveness use get_health instead; for price use get_pricing instead; for live mentions use research_mentions'), and clear constraints on input format (goal sentence, not tool name). This leaves no ambiguity for routing decisions.

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