treasury

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

With annotations already declaring readOnly, openWorld, and idempotent hints, the description adds valuable context: the default free model (Workers AI Llama-3.3-70b), the BYO-key mechanism for Anthropic with a direct-payment note, and the per-model return structure. It also confirms the non-destructive nature aligns with annotations. No contradiction.

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

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

The description is a compact three-sentence paragraph that front-loads the core purpose first. Every sentence adds distinct information (action/score, default model/cost, return shape/use cases) with no redundancy or filler. Ideal length for an agent to parse quickly.

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 clearly explains what the tool returns (per-model {score, confidence, signals, raw_response} + combined view). It covers the key parameter interplay (which model requires which key), cost implications, and concrete use cases. For a tool with 4 parameters and no output schema, this is a complete and self-sufficient 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?

Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the default model for 'models', the relationship between '_apiKey' and 'anthropic' (needed only when that model is listed), and the free vs paid cost implication. It also suggests 'context' usage implicitly via examples, though the schema already covers it. This extra semantic richness justifies 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 clearly states a specific action ('Probe one or more LLMs') and a specific outcome ('score visibility (0-100) per model'), with explicit scope ('business / brand / product / topic'). This distinguishes it from siblings like ask_pipeworx (which likely returns conversational answers) and scan_competitor_ai_presence (which sounds narrower), by emphasizing multi-model visibility scoring.

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 use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), giving clear context for when to use the tool. However, it does not explicitly mention alternatives or when not to use it, which would push it to a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds valuable behavioral context: it routes to 5,529 tools, fills arguments, returns citation URIs, and notes it 'works on every tier, one fast call.' No contradictions. It could mention error/limitation scenarios, but annotations cover the safety profile.

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 average but information-dense. It front-loads the critical instruction ('PREFER OVER WEB SEARCH') and organizes guidance with examples and 'Step up only when needed.' The example list is useful and earns its place. Minor redundancy (e.g., lists of lookup verbs) but overall well-structured.

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, but the description explains that it returns a 'structured answer with stable pipeworx:// citation URIs,' which is sufficient for an agent to know what to expect. It covers usage, caveats, and alternatives. Given the tool's broad scope, it is contextually complete for decision-making.

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 full descriptions for all 6 parameters, including aliases for 'question.' The description's examples ('current US unemployment rate', 'Apple's latest 10-K') add practical context but don't introduce parameter semantics beyond what the schema already provides. 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 clearly states the tool's function: 'Routes the question to the right one of 5,529 tools across 1455 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' It uses a specific verb ('routes') and resource, and explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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: 'PREFER OVER WEB SEARCH', 'START HERE for most questions — this is the default entry point.' It also states when to step up to alternatives: 'for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research.' This is ideal usage differentiation.

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 the experimental nature, notes that no candidate is currently active, and clarifies it is a full working router ('Falls back to nothing'). This goes beyond the annotations by explaining the live-testing behavior and current state.

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 somewhat lengthy but each sentence provides essential context: beta status, current state, usage direction, and functional guarantee. It is front-loaded with the key purpose and avoids redundancy.

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 beta wrapper, the description is sufficiently complete: it clarifies the relationship to the stable tool, the current no-candidate state, and that the response shape matches ask_pipeworx. This is adequate given the straightforward schema and read-only annotations.

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 provides full descriptions for all 6 parameters (100% coverage), so the description adds no additional parameter semantics. The mention of 'same arguments' merely references 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 immediately identifies the tool as a beta version of ask_pipeworx with 'identical universal router' and specifies it is the 'experimental edge'. This clearly distinguishes it from the sibling tool ask_pipeworx while explaining its 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 explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and contrasts it with the stable router. It provides clear usage context and names the alternative, but does not explicitly address when not to use it.

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

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

Beyond the readOnly, idempotent, and openWorld annotations, the description discloses critical behaviors: it only uses the tool result, returns verbatim evidence, and explicitly lists refusal reasons like not_in_source or data_truncated. This goes far beyond the annotations' minimal hints and clearly sets expectations for 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 front-loaded with the core purpose, then expands into behavioral details, usage guidance, and tradeoffs. Every sentence earns its place, and the structure is logical: what it does, how it differs, when to use it, and what to expect. No fluff or repetition.

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 absence of an output schema, the description fully specifies the return structure on success ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and on refusal (explicit reasons). It also covers routing, extraction constraints, and cost/performance tradeoff, making it complete for a high-stakes grounding 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 schema fully documents the single conceptual parameter 'question' with multiple aliases (100% coverage), so the description doesn't need to add semantics. The description mentions 'fills arguments' generically but provides no parameter-specific details; the baseline of 3 is appropriate since the schema does the heavy lifting.

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 function: a hallucination-resistant answer mode that extracts answers using only the tool result, returning evidence and refusals. It distinguishes itself from sibling ask_pipeworx by emphasizing groundedness and explicit refusal behavior, 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 provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and contrasts with the sibling: 'prefer ask_pipeworx for casual lookups.' It also mentions the cost tradeoff of one extra LLM call, helping the agent choose appropriately.

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 read-only/idempotent annotations, the description richly details the resolver contract, fan-out logic, safety short-circuits (low_confidence_match, market_closed_or_inactive), wide-spread handling, and resolution-rule risk with concrete examples. This goes far beyond what annotations provide.

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

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

Although long, the description is front-loaded with purpose and uses all-caps section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES) to organize dense information. Every sentence provides operational detail, with no filler, making it efficient for its complexity.

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 thoroughly explains all response components (result.market, analysis, evidence, parent_event), news fallback fields, and edge cases like closed markets and wide spreads. It also covers blocking paths and resolution-rule risk, making it highly complete for the tool's complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the market parameter input types and provides examples, but these are already in the schema. It does not add significant new meaning about parameter semantics 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly states the input forms (slug, URL, question text) and the intended use cases ('should I bet on X'), which distinguishes it from sibling tools like arbitrage or edge trackers.

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 says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear when-to-use context. However, it does not state when not to use it or mention alternatives, so it stops short of a 5.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints, so the safety profile is covered. The description adds valuable behavioral context: it pulls from SEC EDGAR/XBRL for companies, FAERS for drugs, handles off-calendar fiscal years, sorts by primary metric, and returns citation URIs. This goes beyond the annotations without contradicting them.

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, starting with common language triggers, then type-specific details, output behavior, and an efficiency note. Every sentence serves a purpose; while somewhat long, it's appropriately detailed for a tool with two entity types and no output schema.

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 compensates by stating it returns paired data and pipeworx:// citation URIs. It covers the main use case, data sources, sorting behavior, and the efficiency advantage over sequential lookups. Minor omissions like error conditions or time ranges are acceptable given the tool's simplicity and strong annotations.

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%, but the description enriches both parameters significantly. It explains that type="company" pulls 10-K revenue, net income, cash, and long-term debt, while type="drug" pulls adverse-event counts and trial counts. It also clarifies the values parameter for each type (tickers/CIKs vs. drug names), adding real-world semantics 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 performs side-by-side comparisons of 2–5 companies or drugs in a single call, and provides explicit trigger phrases like "Compare X and Y" and "head to head." It distinguishes itself from sequential single-pack lookups, 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 gives explicit usage directives: "ALWAYS PREFER over sequential single-pack lookups when comparing entities," and provides concrete examples of when to invoke it. It also specifies the behavior for each entity type, giving clear context on when company vs. drug mode 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?

Discloses account requirement, parallel routing to 5,529 tools, output packet structure with gaps[] and contradictions[], citation_uri fetchability, hop fields, semantic excerpting, and latency expectations. This goes well beyond the annotations (readOnlyHint, idempotentHint) and does not contradict them.

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 densely packed with essential information. It front-loads the account requirement and primary purpose, then systematically covers usage guidance, output details, and operational characteristics. While at the upper length limit, every section earns its place and there is no redundancy.

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 fully documents the return format (verbatim evidence, confidence, source, fetched_at, citation_uri, hop, gaps[], contradictions[]) and operational aspects (latency, excerpting, error behavior for missing data). It is self-sufficient for an AI agent to invoke and interpret results.

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

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

Schema covers both parameters fully (100% coverage), but the description adds meaningful behavioral detail: depth:'quick'=3 facets, 'standard'=5 with gap recovery, 'thorough'=8 with iterative chasing, and the paid-plan implication. This goes beyond the schema's enum definitions.

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 deep_research as a grounded multi-source research tool over structured data, specifying the verb (research), resource (1455 structured data sources), and scope (broad/multi-part questions). It explicitly distinguishes it from siblings: 'this is NOT open-web search', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'.

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 explicit when-to-use ('Best for broad/multi-part questions over structured data'), when-not-to-use ('single lookup', 'breaking/colloquial current-news'), and names alternatives (ask_pipeworx). Also includes account requirements and paid-tier restrictions, enabling correct tool selection by an agent.

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 readOnly/idempotent annotations, the description adds significant behavioral context: it returns top-N tools with full input schemas and curated examples, and states results are 'ready to call directly, no second schema lookup needed.' This explains what the agent can expect, going well 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 efficiently structured with a clear opening statement, a useful list of covered domains, and a concise output explanation. Each sentence contributes value, though the domain list is somewhat lengthy; still, it aids in understanding scope.

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 rich schema, clear annotations, and detailed description, the tool is fully contextualized. The description covers what it does, when to use it, and what it returns, leaving no critical gaps for an agent 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?

The schema has 100% coverage with descriptions for all parameters, including aliases. The description does not add additional parameter-level semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose with a specific verb+resource: 'Find tools by describing the data or task.' It distinguishes itself from siblings by focusing on tool discovery rather than direct data access or analysis, and explicitly lists many domains it covers.

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 explicit when-to-use guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and instructs 'Call this FIRST when you have many tools available.' This clearly positions it relative to alternatives and tells the agent exactly when to invoke it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds substantial behavioral context beyond that: patents API sunset with soft-fail, GDELT→GNews fallback, return structure details, and the requirement for zero-padded CIK. This discloses failure modes and data source behavior effectively without contradicting 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 information-dense and front-loaded with user intents and the core promise. It lists return fields compactly with semicolons. However, it is a single long paragraph that could be better structured (e.g., bullet-style) without losing content, so it doesn't earn a 5.

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 exists, the description fully compensates by detailing all return components (cik, recent_filings with URIs, fundamentals, patents, news, LEI) and important caveats (soft-fail, fallback, name limitation). This is complete for a complex fan-out tool.

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

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

Schema description coverage is 100%, and the schema already documents both 'type' and 'value' with examples. The description repeats the ticker/CIK guidance and 'names not supported' but adds no new semantic information beyond what the schema provides. Baseline 3 is appropriate as the schema carries the load.

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 creates a 'full cross-source profile of a US public company in ONE parallel call' with concrete examples. It distinguishes itself from sibling tools like compare_entities and resolve_entity by enumerating the exact return fields and explicitly stating it handles tickers/CIKs, not names.

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 explicit usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a name).' This tells the agent exactly when to invoke this tool versus alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and the memory-system nature, but does not disclose additional behavioral traits beyond that. It aligns with annotations and adds only modest value beyond them.

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 three sentences long, each earning its place: purpose, when-to-use, and related tools. It is front-loaded with the action and contains 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?

For a simple one-parameter deletion tool, the description is complete. It covers purpose, usage conditions, and relationship to sibling tools. The destructive and idempotent annotations cover the safety profile, and no output schema is necessary for this operation.

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 'key' parameter is already well-described as 'Memory key to delete.' The description's 'by key' adds no additional semantic meaning beyond the schema, so a 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 and resource: 'Delete a previously stored memory by key.' This clearly states what the tool does and distinguishes it from siblings like remember and recall.

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 when context is stale, the task is done, or you want to clear sensitive data.' It also mentions pairing with remember and recall. However, it does not explicitly state when not to use the tool, so it falls short of a 5.

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

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

Beyond annotations (readOnlyHint, idempotentHint), the description details the process: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also clarifies the output format and destination, adding value over 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 concise, with the primary purpose stated in the first sentence. It includes useful use cases and output details without unnecessary verbosity, every sentence earns its place.

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

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

For a read-only generation tool with complete schema coverage and annotations, the description adequately explains the output ('single text blob ready to drop at site-root/llms.txt'), use cases, and process. No gaps remain for the agent to correctly invoke and understand the 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 descriptions for both 'url' and 'max_links'. The description does not add significant new parameter semantics beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL.' It specifies the resource (URL) and the output (llms.txt file), and distinguishes it from sibling tools like scan_competitor_ai_presence by focusing on generating the file rather than scanning presence.

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 use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives clear context for when to use the tool, though it does not mention alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by listing the exact return fields (id, type, params, created_at, last_fired_at, fire_count) and clarifying 'active subscriptions' as the default scope.

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

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

The description is two sentences: the first states the core action and the second lists return fields and use cases. Front-loaded, efficient, and every sentence earns its place with no redundancy.

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 list tool with one optional parameter and no output schema, the description fully covers what the tool does, what it returns, and why to use it. It provides sufficient context for an agent to invoke it correctly without needing additional documentation.

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 include_inactive parameter is already well-documented. The description does not add additional parameter details, but the schema carries the full semantic load, so a baseline score 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 gives a specific verb ('List') and resource ('the caller's active subscriptions'), making the tool's purpose unambiguous. It also differentiates from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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 states when to use the tool ('Use this to review what you're monitoring before adding more or to find an id to cancel'). It provides clear context but does not explicitly mention when not to use it or name alternative tools, though siblings are evident from the tool list.

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?

Despite annotations being all false, the description discloses the full operational profile: claim_token return flow, rate limit of 5/day, free usage, daily review cadence, and how to follow up. This goes far beyond what the annotations imply and fully carries the behavioral disclosure burden.

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 paragraph is compact despite covering many nuances. Every sentence contributes: categories, scope exclusions, content guidance, claim-token workflow, rate limits, and cost. It is front-loaded with the primary action and remains focused.

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, four parameters (one nested), and multiple operational behaviors (claim_token, rate limits, scoping), the description is fully sufficient. It tells the agent exactly what to expect (token on filing, status on follow-up) and covers edge cases.

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 already has 100% field descriptions, but the description adds workflow-level semantics: how to use claim_token to check resolution status, what kind of message content is appropriate, and the mandatory tool-scoping context. This elevates parameter understanding 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 first sentence immediately clarifies the action: telling the Pipeworx team something is broken, missing, or needs to exist. It enumerates specific categories (bug, feature/data_gap, praise) and explicitly scopes the tool to Pipeworx's own tools, distinguishing it from sibling research/query 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 explicit when-to-use conditions (bug, feature, data_gap, praise) and when-not-to-use guidance (tools from other MCP servers should be reported elsewhere). Also gives content rules (describe in Pipeworx tool terms, don't paste end-user prompts).

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description discloses that the data is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This adds meaningful behavioral context about data source, privacy, and freshness without contradicting 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 well-structured: an opening purpose statement, a numbered use-case list, and a data provenance note. Every sentence adds distinct value—purpose, application, and behavioral details—without redundancy or fluff. The layout is scannable and front-loaded with the core function.

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 simplicity (one optional parameter, no output schema), the description is complete. It explains the return shape ('top tools, top packs, and total call volume' and '(pack, tool, count)'), the optional window parameter, and the caching behavior. It provides enough context for an AI agent to correctly invoke and interpret results without needing further documentation.

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 fully describes the window parameter with enum values and a helpful description, so the baseline is 3. The tool description adds extra meaning by explaining the impact of window choice ('Shorter windows surface what's hot right now; longer windows show steady-state demand') and linking window to cache duration, going 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 first sentence 'What other AI agents are calling on Pipeworx right now' immediately states a specific verb and resource, while 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d)' clearly defines the output scope. This distinguishes it from sibling tools like ask_pipeworx or discover_tools by focusing on aggregate cross-agent activity rather than individual queries.

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 an explicit 'Useful for' list with three concrete scenarios: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent needs. While it doesn't explicitly state when not to use it or name alternative tools, these usage contexts are 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?

Annotations declare readOnly/idempotent, but the description adds substantial behavioral detail: placeholder filtering, >20% placeholder fraction returns null, Jaccard similarity threshold, and the fill-check behavior against live CLOB depth. It also discloses outputs and edge cases 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?

The description is dense and long, but front-loaded with purpose and organized into labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Some sentences are run-ons, but the complexity justifies the length; 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?

Even without an output schema, the description fully specifies the response shape: opportunities[] fields, partition_check fields, and fill_check result semantics. It also covers failure modes like skipped_low_similarity and null arb signal.

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 descriptions cover 100% of parameters, the description adds meaning: event accepts slug or full URL, topic acts as a seed question, and explains what each mode computes (partition_check, comparator on union). This exceeds the schema's basic definitions.

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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'. It clearly distinguishes the three invocation modes (no args, event, topic) and differentiates from sibling tools like polymarket_fill_risk by noting fill pricing is separate.

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

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

Explicit guidance is provided: no args for trending_scan, recommended event for a specific market, topic for cross-event scanning, with examples. The FILL CHECK section explicitly says don't trade when realizable_edge_pp <= 0 and directs to polymarket_fill_risk for custom sizing.

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

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

Annotations already mark it read-only and idempotent, but the description adds substantial behavioral context: 'Cached 1h at the KV level,' 'Fed bets surface here, excluded from ranking,' 'min_kelly never filters them,' and detailed filtering logic (placeholder-slug drops, >20% skip). This goes well beyond the structured 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 extremely dense, with multiple parentheticals and technical details (e.g., 'per-sport α (tennis 1.02, soccer 1.10, MMA 1.15)'), and is presented as a single block of text with no structured breaks. While every sentence adds value, the sheer length and lack of formatting make it harder to parse quickly.

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

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

With no output schema, the description carries the burden of explaining the return value, and it does so thoroughly: it names the top-level keys (by_segment, fed_candidates, _diagnostics), per-opportunity fields, and even the 'WHY a segment is empty' diagnostics. Caching behavior is also disclosed, making the tool's behavior fully predictable.

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%, but the description adds meaningful semantics for the knobs: 'TRADEABLE-EDGE KNOBS: min_liquidity / max_spread_pp drop opportunities where edge isn't realizable' and the interaction note that 'partition arbs always return kelly_fraction_half=0 at the parent level... so min_kelly never filters them.' This clarifies cross-parameter behavior.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes it from data feeds or analysis tools, and the 'what should I bet on today' framing reinforces its decision-support 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 phrase 'Built for "what should I bet on today"' provides a clear use case, and the detailed knob explanations (e.g., 'Set to 2 to require tight books') indicate when to adjust parameters. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so it lacks explicit when-not/alternative guidance.

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

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

Annotations already declare the tool read-only and idempotent, but the description adds extensive behavioral detail: the 60-day snapshot TTL, decay computed from daily closes, the meaning of snapshot_dates gaps, and how expired opportunities are determined. This goes far beyond the structured 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 long but well-structured, with clear sections covering purpose, arguments, response fields, and limitations. Each sentence provides substantive detail, though some parts (e.g., the parenthetical about decay direction) could be more concise without losing meaning.

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 fully specifies the response structure (tracked, expired, snapshot_dates), explains field semantics, and discloses important limitations like TTL and snapshot gaps. For a read-only analytics tool with two optional parameters, this is completely adequate and even thorough.

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 both parameters, but the description adds meaningful extras: days default of 14 and max of 30 (schema only says clamp 2-30), window default of '1wk', and clarifies that window refers to the snapshot family. This is above the baseline 3 because it provides practical usage details 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 clearly states it provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from the sibling polymarket_edges tool by focusing on historical persistence across snapshots rather than current edge values, making the purpose unambiguous.

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

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

The description gives clear context for when to use it, contrasting fresh vs. old edges ('a fresh wide edge and a 3-week-old wide edge are different trades') and explicitly answers a use-case question. However, it does not explicitly name alternative sibling tools or state when not to use this tool, which prevents a perfect score.

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 state readOnlyHint=true and destructiveHint=false, and the description adds extensive behavioral context: it 'walks the ladder', returns per-leg fill details, identifies thin_legs, and warns that forced_directional_risk names legs 'most likely to strand you unhedged'. It also highlights the real-world consequence of partial fills, which is not captured by 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 every sentence carries useful information, but it is long and compacted into paragraphs. The use of uppercase markers (SINGLE-MARKET, BASKET, USE THIS) helps scannability, yet bullet points or line breaks would improve readability. Still, it is appropriately sized for the tool's complexity.

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 fully carries the burden of explaining return values. It enumerates all key outputs for both modes: top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for basket mode: theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg detail, thin_legs, max_clean_notional_usd, forced_directional_risk. Combined with usage guidance and behavioral warnings, it is contextually 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?

Although schema description coverage is 100%, the description adds crucial mode-specific meaning beyond the schema: it explains that 'market' is for single-market mode and 'event' for basket mode, details how size_usd is interpreted differently in each mode (max spend/proceeds vs settlement notional), and clarifies side defaults per mode. This rich semantic mapping far exceeds what the schema alone offers.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two operation modes (single-market and basket) and its purpose is distinct from sibling tools like polymarket_arbitrage and polymarket_edges, which are about finding opportunities rather than validating fillability.

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

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

Explicit guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial basket fills convert arb into unhedged positions), giving both when and why to use this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes far beyond these by detailing response structure, compatibility_warning conditions, temporal_alignment semantics, and skipped_cross_type counters. 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 long (~250 words) but well-structured with clear sections for modes, response, safety fields, and caveats. It is front-loaded with the core purpose. Slightly verbose, but the density is justified by the tool's complexity.

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 fully specifies return values: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning triggers, temporal_alignment, and skip counters. It covers edge cases (e.g., semantically unrelated events) and explains the meaning of each safety field.

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 substantial param semantics: it lists the 10 topic shortcuts, explains that explicit kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and describes the two modes. This is meaningful guidance 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 defines the tool's function: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It is specific and distinguishes from siblings like polymarket_arbitrage by focusing on the Kalshi–Polymarket comparison.

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 outlines two usage modes (topic shortcuts vs explicit tickers) and provides important caveats, such as 'pre-mapped ≠ tradeable' and when compatibility_warning indicates non-equivalent bet shapes. However, it does not explicitly reference alternative sibling tools (e.g., polymarket_arbitrage), so it lacks direct when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: it mentions that data is 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID)' and that omitting the key lists all saved keys. This provides useful information about the tool's access boundaries and 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 description is three sentences, with the primary action front-loaded in the first sentence. It efficiently covers purpose, usage, scoping, and related tools without unnecessary filler. Every sentence earns its place, making it highly concise and well-structured.

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 tool with one optional parameter, the description is complete. It explains what the tool does, how to use it, when to use it, how it relates to remember and forget, and its scoping behavior. The schema and annotations already cover parameter details and safety, so no further explanation of return values is needed.

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 'key' parameter, so the baseline is 3. The description adds semantic meaning by providing examples of what keys might represent ('the user's target ticker, an address, prior research notes') and clarifies that omitting the key lists all saved keys, reinforcing the schema's description while giving practical context for key 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 states the tool's function: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It uses a specific verb ('retrieve') and names the resource (values saved via remember), while also distinguishing from the sibling tools 'remember' and 'forget' by explicitly pairing with them.

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 guidance on when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also names the complementary actions 'remember' to save and 'forget' to delete, which clarifies the alternative tools and their distinct roles.

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 a meaningful side effect: setting mark_read:true flags returned events read so the next call only shows newer ones. This directly contradicts the annotations that declare readOnlyHint=true. Even though the description is otherwise transparent, the contradiction with the structured annotation forces a score of 1 per the rubric.

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

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

Three dense, front-loaded sentences deliver purpose, return shape, filtering, state side effect, and an alternative access method. No filler or repetition—every sentence earns its place.

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

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

Despite no output schema, the description tells you exactly what the returned events carry (source, citation_uri, raw payload), explains persistence and polling behavior, covers filtering, and provides an external endpoint for scripts. This is complete for an agent to decide and invoke the tool correctly.

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

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

The input schema already covers all five parameters with descriptions, but the tool description adds crucial semantics: type is exemplified with 'sec_8k', since expects an ISO timestamp, and mark_read's effect on subsequent calls is explained. This goes beyond bare parameter names, though limit and unread_only are left to schema 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?

The description opens with a specific verb and resource ('Pull fired events from your subscription feed'), then details what each event carries. This clearly distinguishes the tool from siblings like list_subscriptions (which lists subscriptions) and recent_changes (which tracks changes), making the purpose unambiguous.

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

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

It gives clear context: it describes filtering options, mentions that polling works fine, and points to an HTTP alternative for scripts/dashboards. It does not explicitly compare to sibling MCP tools, but the usage context is evident and practical.

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 richly discloses behavior beyond the annotations: fan-out to SEC EDGAR, GDELT→GNews fallback for rate limits/5xx, PatentsView API sunset with soft-fail, accepted `since` formats, and the return structure. These details align with readOnlyHint and idempotentHint, 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 dense and every sentence adds value, but the long list of example queries (six iterations) is somewhat verbose. It is front-loaded with intent and goes from purpose to details to alternatives in a logical sequence.

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 description covers sources, fallback logic, date syntax, return shape (changes[], total_changes, citations), and the sibling distinction, which is substantial for a tool with no output schema. However, it does not detail the fields inside changes[] or error handling (e.g., unknown ticker), leaving some invocation-time uncertainty.

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 descriptions for type, value, and since, so the baseline is 3. The description only restates the since format without adding new parameter-level semantics, such as usage of type or 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 uses a specific verb phrase ('change feed for a company in the last N days/weeks/months') and grounds it with multiple natural-language examples ('What's new with X', 'updates on Acme'). It explicitly distinguishes from the sibling tool entity_profile, naming the appropriate alternative for static profiles.

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 indicates when to use this tool (changes over a window) and explicitly directs users to entity_profile when a static profile is desired. It also notes the 'ONE parallel call' advantage, giving efficiency context.

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 beyond the annotations by disclosing scoping ('scoped by your identifier'), persistence rules (authenticated vs. anonymous TTL of 24 hours), and the existence of a paired delete tool. This adds significant context not found in the structured annotations and does not contradict any hint.

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

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

The description is two sentences, front-loaded with the core action, and every sentence earns its place. It includes usage guidance, storage details, and companion pointer without 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 simple key-value store with two required parameters and no output schema, the description covers the what, when, why, and how. It also clarifies persistence behavior and integration with sibling tools, making it sufficiently complete for an agent to invoke 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?

The schema already covers both parameters with clear descriptions and examples (100% coverage). The description adds conceptual context but does not meaningfully extend the parameter semantics beyond what the schema provides; thus 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 uses a specific verb and resource ('Save data the agent will need to reuse later'), clearly distinguishes the tool from sibling tools like recall and forget, and explains the key-value storage model. It is not just a restatement of the title.

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 it ('Use when you discover something worth carrying forward') and names alternatives and companions ('Pair with recall to retrieve later, forget to delete'). It also covers cross-session vs. same-session usage with persistence differences.

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 adds significant behavioral context beyond the annotations: identifiers are source-labelled, unresolved ones are explicitly listed, and LEI/FIGI enrichment degrades gracefully if external sources are unavailable. It also explains that each call cascades through multiple internal endpoints.

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 well-structured, starting with example queries, then the core purpose, then detailed type breakdowns. Every sentence adds value, though it could be slightly tightened without losing 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?

With no output schema, the description compensates by explaining key return behaviors: source labels, explicit unresolved identifiers, and graceful degradation. It also covers both supported entity types in depth, making it complete for a tool of this complexity.

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

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

Although the schema already covers both parameters (100% coverage), the description enriches them with concrete input examples, supported identifier formats, and what each type returns (e.g., CIK, ticker, LEI, RxCUI). This goes far beyond the schema definitions.

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 resolves user-spoken names into canonical identifiers, with specific verbs and resources. It also distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID,' 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 provides a clear when-to-use instruction: 'Use FIRST whenever you have a name but need an ID.' It does not explicitly mention exclusions or name alternative tools, 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?

Annotations already signal a safe read-only, idempotent operation, so the description adds value by detailing the probe-and-rank behavior, the 'subject' treatment of the first entity, and the specific return fields (score, confidence, signal density). This goes beyond the structured metadata without contradicting it.

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

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

The description is two sentences with every clause earning its place: it states the action, the mechanism, the use case, and the return format. No wasted words, front-loaded with the primary purpose.

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 explicitly states what is returned (ranked list with score, confidence, signal density) and covers the key behavioral aspects (probing, ranking, surfacing). With annotations covering safety and schema covering parameters, the description is complete and self-sufficient.

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 the key nuance that the first entity in the array is treated as the 'subject' for narrative, which is not in the schema, and clarifies the overall comparison intent for the entities parameter, adding real semantic 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 verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It clearly distinguishes itself from the sibling ai_visibility_check by explaining this tool probes multiple entities and ranks results, making its unique 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 provides a concrete use case ('competitive AI-marketing audits') and an example query, clearly implying this is for multi-entity comparison. It does not explicitly name alternatives like ai_visibility_check for single-entity checks, but the context makes the intended usage 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?

Annotations declare readOnly and idempotent, but the description adds significant behavioral context beyond that: it is a composite call fanning out to two services, partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s and may appear in 'sources_failed', and the return shape includes a summary block and alternate versions. 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 front-loaded with the main purpose in the first clause, and every subsequent sentence adds essential information: use cases, return contents, ecosystem scope, and failure behavior. Despite being longer than a simple one-liner, it is dense, well-structured, and free of 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?

For a composite tool with no output schema, the description thoroughly covers what the agent needs: the exact summary fields, per-advisory detail, links, alternative versions, and partial failure semantics. It also notes the 5-30s delay possibility. This is a complete contextual picture for invocation and result interpretation.

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 clear descriptions for both 'package' and 'version'. The description does not add extra parameter-level semantics beyond what the schema already provides, so the baseline of 3 is appropriate. It does mention scoped package acceptance, but that is already in the schema.

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

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

The description opens with a specific and actionable purpose: 'Composite "should I add this npm package to my project" check in ONE call' and clearly enumerates the data sources (deps.dev, bundlephobia) and the questions it answers ('is X safe / popular / small'). It fully distinguishes itself from sibling tools by focusing on npm package evaluation with concrete resources.

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

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

Explicit usage guidance is provided: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states an exclusion: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving clear when-to-use and when-not-to-use context.

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, openWorldHint, idempotentHint, and non-destructive. The description adds substantial behavioral context beyond that: return format (character offsets and similarity scores), embedding model (BGE-base-en), search window (500-char overlapping), and the 200K character cap with truncation flag. 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 three sentences, each earning its place: the first defines function and output, the second explains when to use it, and the third adds technical constraints and pairings. No redundant phrases or filler; it is front-loaded and compact.

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 though there is no output schema, the description explicitly states the return shape (passages with offsets and similarity scores) and the truncation behavior. It also covers performance details (500-char windows, cap), pairing with ask_pipeworx_grounded, and the primary use case, making it complete for an agent to select and invoke 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?

The schema already covers all three parameters with descriptions, so baseline is 3. The description reinforces the text/query relationship and mentions 'top-N passages' (matching limit), but it does not add new meaning beyond the schema descriptions. It integrates parameters into the use case but doesn't go 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 opens with a specific action: 'Semantic search INSIDE a fetched record', clearly naming the resource (the text passed in) and the output (top-N passages with offsets and similarity scores). It also distinguishes itself from siblings by explicitly pairing with ask_pipeworx_grounded and emphasizing local search over already-fetched content.

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 a clear when-to-use condition: 'Use when the record is too big to cram into the prompt'. It also names the sibling alternative/companion (ask_pipeworx_grounded) and explains the complementary workflow. However, it lacks an explicit 'when not to use' or guidance for small records.

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 adds valuable behavioral details beyond the annotations: it requires an OAuth account, phone verification for SMS, and a 10/day cap. It also explains the always-on feed and optional email/SMS channels. No contradiction with annotations; the create action aligns with readOnlyHint=false and destructiveHint=false. It does not explicitly describe idempotency, but the annotation covers that.

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 information-dense but well-structured, starting with the core purpose and then detailing types and delivery options. It is somewhat long, but every sentence adds useful information. The omission of webhook from the prose is a minor structural gap, preventing a full 5.

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 high schema coverage, the description lists only 3 of the 5 supported subscription types (sec_8k, polymarket_edge, fred_series) while omitting patent_grant and clinical_trial. Since it says 'Supported types:' without qualifiers, this could mislead an agent into thinking the omitted types are unsupported. It also omits webhook as a delivery channel in the prose, and does not mention the output schema (which does not exist). These gaps reduce completeness for a complex 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%, so the baseline is 3. The description adds extra meaning by providing concrete examples for each subscription type (e.g., sec_8k items:["5.02"]) and clarifying delivery constraints like the phone verification and SMS cap. However, it omits webhook from the prose description (though the schema covers it), so it does not fully compensate for all parameter nuances.

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: 'Create a proactive monitoring subscription to a live-data event stream' and mentions it returns the new subscription id. The verb 'Create' and resource 'subscription' are specific, and the tool is clearly distinguished from sibling tools like list_subscriptions and unsubscribe.

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 context on when to use the tool (for proactive monitoring) and mentions pull alternatives (recent_alerts or alerts.json). It also gives an important exclusion: requires a Pipeworx OAuth account and that anonymous + BYO cannot persist subscriptions. However, it does not explicitly contrast with sibling tools beyond this, so it stops short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context about the live catalog source, the nature of the output (tool shapes), and how topic scopes the results, exceeding the annotation baseline.

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 information-dense and well-structured, opening with example queries and then defining purpose, output, and usage. It is longer than minimal but every sentence contributes value, and the list of categories is organized for scanability.

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 simple schema, rich annotations, and lack of an output schema, the description covers all essentials: what it returns, when to use it, parameter behavior, and its role in the meta-tool ecosystem. An agent can confidently invoke this tool based on the description alone.

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 describes topic with enum-like values and has 100% coverage. The description enriches this by providing concrete examples ('finance', 'pharma', 'betting') and clarifies that omitting it returns a full cross-category spread, making the parameter's behavior more tangible.

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 function: it returns category-bucketed example questions with the exact tool+argument shape that answers them, directly positioning itself as the onboarding entry point. It distinguishes from siblings like ask_pipeworx by framing it as the 'first' tool to use when unsure of Pipeworx's capabilities.

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 instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools,' providing clear context for when to invoke. Also explains the no-args vs topic behavior. It doesn't explicitly list when-not scenarios, but the 'FIRST' directive implies alternatives for later stages.

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

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

Adds valuable behavioral details beyond annotations: ownership enforcement, deactivation rather than deletion, and persistence of historical events via recent_alerts. This complements the idempotentHint and destructiveHint, enhancing the agent's understanding of side effects.

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 concise sentences, each contributing essential information: the action, the ownership restriction, and the deactivation behavior. No unnecessary words or repetition.

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 tool with one parameter and no output schema, the description covers the key side effects and links to recent_alerts. It does not describe return values or error cases, but those are secondary given the tool's simplicity and annotation coverage.

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 fully documents the single 'id' parameter as a uuid returned by subscribe, so the schema already provides the necessary semantics. The description adds no further parameter detail, earning the 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?

The description clearly states 'Cancel a subscription by id' — a specific verb and resource. It distinguishes the tool from siblings like subscribe and list_subscriptions by focusing on cancellation, and the 'by id' clarifies the input.

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 clear context for when to use the tool: when you need to cancel a subscription and the ownership is enforced. It also references recent_alerts for historical events, giving an alternative for viewing deactivated subscriptions, but does not explicitly exclude other 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?

Beyond the readOnly/idempotent annotations, it provides rich behavioral detail: the verdict list, the crucial distinction between could_not_verify (system error) and unsupported (no source), the citation format, and the fact that it replaces 4–6 sequential calls. This prevents misinterpreting error cases.

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 each section earns its place: trigger phrases, use case, pathway routing, output semantics, and caller caveats. It is well-organized and front-loaded, though slightly verbose for a tool with only two parameters.

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 fully compensates by listing all verdict types, explaining the error semantics of could_not_verify, and describing the evidence/citation format. It also explains the tool's advantage over multi-step lookups, giving the agent complete 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 covers both parameters fully, so the baseline is 3. The description adds substantial extra guidance on tolerance_pct—overriding implied tolerance, setting 1–2 for hallucination detection, and the default cap of 5—which goes 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 opens with trigger phrases and explicitly states 'natural-language claim verification against authoritative sources.' It also distinguishes two routes (SEC EDGAR for company financials, grounded pipeline for other claims), making it unmistakably the fact-checking tool among 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 explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and explains routing by claim type. It does not name alternative tools or provide explicit 'when-not' guidance, but the directive is clear.

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