Fred

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds that it probes multiple LLMs, defaults to Workers AI, requires BYO key for Anthropic, and returns per-model score/confidence/signals/raw_response plus combined view. 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 concise (4 sentences), front-loaded with purpose, and every sentence adds value. 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 4 parameters, no output schema, the description adequately explains return format (per-model {score, confidence, signals, raw_response} + combined view). Covers all necessary usage details.

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

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

All parameters have schema descriptions (100% coverage). The description adds context: default model is Workers AI Llama-3.3-70b, 'anthropic' model requires _apiKey, context helps disambiguate. This adds value beyond 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 probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100). It distinguishes itself from siblings like scan_competitor_ai_presence by focusing on multiple models and 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 explains when to use (AI-marketing audits, pre-launch brand checks, competitive monitoring) and how to use default vs. Anthropic model. It does not explicitly list when not to use, but context implies usage.

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, so the bar is lower. The description adds valuable context: routes to 5,529 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and makes one fast call. This goes 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?

The description is lengthy but well-structured and front-loaded with the crucial 'PREFER OVER WEB SEARCH' directive. Every sentence earns its place by covering scope, examples, alternatives, and behavioral guarantees. Slightly verbose, but appropriate given the tool's broad applicability.

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

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

For a complex tool with no output schema, the description is exceptionally complete. It explains what the tool does, when to use it, how it behaves (routing, citations, speed), and provides concrete examples. The absence of an output schema is mitigated by stating it returns a structured answer with stable citation URIs.

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 does not add meaning beyond the schema for the 'question' parameter; it only reinforces the natural-language expectation via examples. The schema already documents aliases and gives examples, so no additional semantics are contributed.

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 answers factual questions by routing to thousands of verified sources, and explicitly distinguishes itself from siblings ask_pipeworx_grounded and deep_research. It gives a specific verb (ask) plus resource (Pipeworx) and a detailed scope of topics.

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 cues ('what is', 'look up', 'find', etc.), says 'START HERE for most questions', and gives precise exclusions: use ask_pipeworx_grounded for hallucination-resistant single answers and deep_research for broad multi-part questions. Even addresses breaking-news case.

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

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

Annotations already declare readOnly/idempotent, and the description adds the experimental nature with candidate routing improvements that may be active, plus current state of matching ask_pipeworx exactly. This is useful context beyond annotations, though it lacks details on potential behavioral differences when a candidate is under test.

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

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

The description is a single dense paragraph but each sentence provides meaningful information about purpose, current state, usage, and safety. It could be more structured with bullet points, but overall it is concise and front-loaded.

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

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

The description covers purpose, relationship to ask_pipeworx, current behavior, and experimental status. It references the same response shape as ask_pipeworx, filling the gap of no output schema. Missing explicit mention of ask_pipeworx_grounded, but that is a minor omission.

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 100% of parameters, all being aliases for the required 'question' field. The description adds nothing beyond stating 'same arguments', so the schema carries the full burden. 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 identifies the tool as a beta version of ask_pipeworx, a universal router handling 5,529 tools. It distinguishes itself from ask_pipeworx by noting experimental routing improvements, but does not mention the sibling ask_pipeworx_grounded.

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: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains the evaluation purpose. Also clarifies current equivalence to the stable router, implying when to choose this beta over the stable alternative.

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, etc.), the description details the routing process, extraction behavior, refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error), and the additional LLM call cost. This adds rich behavioral context 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 dense but every sentence earns its place: it states the core purpose, explains the mechanism, returns the expected output, lists refusal cases, and gives usage guidance. It is front-loaded with 'Hallucination-resistant answer mode' and structured logically.

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 fully explaining the return structure {answer, evidence, confidence, source, fetched_at, refusal_reason} and all possible refusal reasons. It also covers when to use the tool and cost trade-offs, making it complete for an agent.

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

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

Schema coverage is 100% with all six parameters described (five as aliases, one as 'Your question in natural language'). The description adds no parameter-specific details beyond what the schema already provides, so the baseline 3 is appropriate.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and clearly explains it EXTRACTS the answer using ONLY what the tool result contains, distinguishing it from ask_pipeworx. It specifies the return format and refusal reasons, making the tool's 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?

Explicit guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on' and 'prefer ask_pipeworx for casual lookups.' It also notes the extra LLM call cost, giving clear when-to-use and when-not-to-use criteria relative to a sibling tool.

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

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

The description extensively discloses behaviors: market resolution, classification, fan-out, evidence packet, market-vs-model comparison, response shapes, resolver contract, parent_event extractor, news fields with fallback, safety (low-confidence, closed markets), wide-spread markets, and resolution-rule risk. Annotations (readOnlyHint, idempotentHint, etc.) are consistent and the description adds significant 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 front-loaded with the core purpose and use cases, but it is quite lengthy with extensive details on resolver contract, news fields, and safety. While all information is useful, the verbosity could be trimmed slightly for conciseness.

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

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

Given the tool's complexity (multiple classifiers, fan-outs, response shapes, safety checks), the description is remarkably complete. It covers edge cases, fallback mechanisms, and provides sufficient context for an agent to use the tool correctly. No output schema exists, but the description compensates by detailing response shapes.

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 descriptions for all 3 parameters (100% coverage). The description adds further context: examples of market input (slug, URL, question text), depth options (quick vs thorough), and include_raw behavior. This additional meaning justifies a score above the baseline of 3.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (research), resource (Polymarket bet), and action (pulling data). It also distinguishes from sibling tools by detailing the fan-out and comparison features.

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".' This provides clear use cases. However, it does not explicitly mention when not to use the tool or list alternatives among the many sibling tools.

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

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

Annotations declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable context: for 'company' type, it fetches specific financials from SEC EDGAR/XBRL with correct fiscal year handling; for 'drug' type, it pulls FAERS data. 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?

Approximately 150 words, front-loaded with trigger phrases and usage guidance. Every sentence adds information without redundancy. Highly efficient.

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

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

Given complexity (two entity types, different data sources), description explains data sources, sorting, output includes citation URIs, and states efficiency ('replaces 8–15 sequential lookups'). No output schema, but description sufficiently covers returns.

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 both parameters with enums and constraints; description adds meaning by explaining behavior differences between 'company' and 'drug' and giving concrete examples for 'values' array.

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

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

The description explicitly states the tool's function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It provides trigger phrases like 'Compare X and Y' and distinguishes from sequential lookups, making purpose clear.

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 advises to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It does not explicitly exclude single-entity use but implies when to use via examples. No alternatives named.

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

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

The description goes far beyond the annotations: it discloses account/paywall requirements, expected latency (15–60s, up to ~90s), the parallelism across 5,529 tools, gap handling ('explicit gaps[]'), contradiction detection, citation resolvability, and semantic excerpting. No contradiction with the readOnlyHint/openWorldHint annotations exists.

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 and front-loaded with the critical ACCOUNT REQUIRED warning. It packs a large amount of useful behavior into organized sentences; minor redundancy exists because it repeats some schema details about depth, but every sentence does add operational or selection-relevant context.

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

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

For a complex tool with no output schema and minimal annotations, the description is remarkably complete: it covers return value shape (findings packet with evidence/confidence/source/fetched_at/citation), gaps[], contradictions[], failure modes for unsupported topics, auth/tier requirements, latency, and alternatives. Nothing critical is missing for an agent to decide whether and how to invoke it.

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

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

The input schema already has 100% coverage and detailed descriptions, so the baseline is 3. The tool description adds extra semantic context by giving example question types ('compare X and Y's regulatory + financial exposure') and explaining how depth values map to gap recovery and contradiction scanning in plain language, though much of it duplicates the schema.

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

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

The description states a specific verb ('research') and a specific resource ('Pipeworx's 1455 STRUCTURED data sources'), and clearly distinguishes this from sibling tools by emphasizing 'this is NOT open-web search' and 'in ONE call'. It also contrasts with ask_pipeworx for single lookups and current news.

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 provides when-to-use and when-not-to-use guidance: 'If you are not signed in, use ask_pipeworx instead', 'For a single lookup use ask_pipeworx', and 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. It also differentiates depth levels and explains which scenarios benefit from standard vs thorough.

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?

Description adds detail beyond annotations: returns top-N relevant tools with schemas and examples, ready to call directly. Annotations already indicate readOnly and idempotent, so description complements 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?

Description is front-loaded with purpose and includes a useful list of domains. Slightly long but each sentence adds value.

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, description adequately explains what is returned (names, descriptions, schemas, examples). Covers usage and behavior comprehensively.

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

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

Schema coverage is 100% and description reiterates alias behavior and provides examples. While helpful, it does not add significant meaning beyond the schema.

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

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

The description clearly states it finds tools by describing data or task, listing many domains. It distinguishes itself from sibling tools like fred_search by being a meta-discovery tool, not a specific data source tool.

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

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

Explicitly advises to 'Call this FIRST when you have many tools available and want to see the option set'. Provides clear context for when to use, though does not explicitly state when not to use.

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

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

Annotations already mark it as read-only, open-world, idempotent, and non-destructive. Description adds context about data sources, patent soft-failure, and output structure, enhancing transparency beyond 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?

Description is front-loaded with examples and structured logically. Slightly verbose but every sentence adds value; could be trimmed minimally.

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

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

No output schema exists, but description lists all major output fields and sources. Covers complexity of multi-source profile adequately. Patent soft-failure is noted.

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 provides 100% coverage with descriptions for both parameters. Description adds examples ('AAPL', '0000320193') and reinforces that names are not supported, adding practical 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?

Description provides numerous example queries and explicitly states it returns a full cross-source profile of a US public company. It lists the specific data sources and output fields, and distinguishes from sibling tools like resolve_entity.

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

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

Clear guidance to prefer this tool over chaining individual lookups for holistic views. Also explains when not to use it (if only have a name, use resolve_entity first).

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 indicate destructiveHint=true and idempotentHint=true. The description reinforces the destructive nature ('Delete') and adds context about clearing sensitive data, which is valuable behavioral information. No contradictions; the description enhances transparency beyond 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 two sentences, front-loaded with the action, and every word adds value. No unnecessary text.

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 single-parameter deletion tool with no output schema, the description fully covers purpose, usage, and parameter meaning. No gaps remain.

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 has 100% coverage with a clear description for the 'key' parameter ('Memory key to delete'). The description adds no additional meaning beyond restating the parameter's purpose. 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 clearly states the action ('Delete a previously stored memory by key'), specifies the resource ('memory'), and distinguishes from sibling tools 'remember' and 'recall' which are mentioned as paired operations. This meets the highest standard of purpose clarity.

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 lists use cases ('when context is stale, the task is done, or you want to clear sensitive data') and directs to paired tools ('Pair with remember and recall'). This provides excellent when-to-use and 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that it returns subcategories and series IDs, providing useful behavioral context 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?

A single, efficient sentence that front-loads the key purpose. No extraneous information.

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

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

Given the annotations and output schema, the description provides enough context for a browse tool. Could mention pagination, but overall adequate.

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 parameters. The description adds minimal extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the verb (browse), resource (economic data by category), and output (subcategories and related series IDs). It distinguishes from sibling tools like fred_get_series.

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 describes the context for using this tool (to browse by category) and implicitly suggests alternatives for specific series data. However, it lacks explicit 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 read-only, idempotent, and non-destructive. The description adds context about data granularity (country/state/metro), frequency (monthly/quarterly), return format (dates + values + units), and clarifies terminology (e.g., RHORUSQ156N is homeownership rate, distinct from mortgage rate). It goes beyond 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 thorough but not overly verbose. Every sentence adds useful information: authoritative source, data scope, examples, return format, usage context, and alternative tool. It is front-loaded with the core purpose and remains organized despite its length.

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

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

Given the tool has 7 parameters, annotations, and an output schema, the description is remarkably complete. It explains what data is returned, clarifies the difference between similar series, states the tool's scope, and provides fallback guidance. It covers all essential aspects an agent needs to select 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?

Schema coverage is 100%, so baseline is 3. The description adds value by interpreting several series IDs (e.g., MORTGAGE30US, RHORUSQ156N) and noting they are aggregates. It doesn't explain all parameters, but the schema already does that; the examples help disambiguate similar series.

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 this tool fetches historical time-series data for US economic indicators from FRED. It gives specific verb+resource ('historical time-series for US economic indicators') and provides examples of series IDs, distinguishing it from siblings like fred_search and fred_series_info.

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

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

It explicitly says 'Use for macro, Fed, and metro-level indicator questions' and gives an alternative: 'If you don't know the series ID, call fred_search first.' This provides clear when-to-use and 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, idempotentHint, openWorldHint, no destructiveness. The description adds that it returns 'release name + date, newest/upcoming first by default', and mentions future scheduled dates. This enriches the behavioral profile beyond annotations, though pagination or data freshness could be noted.

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

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

The description is compact (3 sentences) and front-loaded with the core value proposition and use cases. Every sentence adds information: what it does, when to prefer it, how to use parameters. No wasted words.

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

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

Given the tool's simplicity (4 parameters, no output schema), the description fully covers return format ('release name + date'), default sorting, and parameter usage. The context signals show high schema coverage, so no missing critical information. The description is complete for an agent to use 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?

Input schema has 100% coverage, but description adds meaningful value: explains that omitting release_id gives cross-release calendar, passing it gives one release schedule, and gives concrete examples (10=CPI, 50=Employment Situation, 53=GDP). It also states default sort_order is desc. This goes beyond 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 clearly states the tool provides an economic data release calendar from FRED with future dates. It uses specific verbs ('release calendar', 'the dates indicators are/were published') and distinguishes itself from siblings like fred_releases by focusing on dates. Examples of use cases ('when is the next CPI / jobs report / GDP release') further clarify purpose.

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

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

The description explicitly advises when to use this tool over web search ('PREFER OVER WEB SEARCH'), explains when to omit or include release_id, and provides example release IDs for common economic indicators. This gives clear context for proper selection and invocation.

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 readOnly, idempotent, non-destructive, and openWorld. The description adds that it returns specific data fields, clarifying the output. Together they provide good transparency; no behavioral details are hidden.

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 long with no unnecessary words. It front-loads the purpose and return information, making it efficient and easy to scan.

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 interface (3 parameters, 1 required, output schema present) and annotations, the description sufficiently covers what the tool does, its safety profile, and its output. No critical gaps remain.

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 input schema already documents all parameters. The description adds no additional parameter context beyond what the schema provides, meeting the baseline for high coverage.

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

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

The description clearly states the tool checks upcoming and recent economic data releases and lists the return fields (dates, names, which series). It uses a specific verb (check) and resource (releases), but does not explicitly differentiate from sibling tools like fred_release_dates, which might overlap.

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

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

No guidance is provided on when to use this tool versus alternatives such as fred_release_dates or fred_search. The description implies its purpose but does not state exclusions or prerequisites.

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 supply readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description does not add further behavioral details (e.g., pagination, output format hints), but also does not contradict annotations.

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

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

Two sentences convey the core purpose and output efficiently 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?

Given the presence of an output schema and rich annotations, the description covers the essential information. However, a brief note on when to use this over other FRED tools would enhance completeness.

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

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

Schema coverage is 100% and examples are provided. The description does not elaborate on parameters beyond the schema, which is acceptable. 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 action ('search for economic data series by keyword') and specifies the return values ('series IDs, titles, and descriptions'), effectively distinguishing it from sibling tools like fred_category or fred_get_series.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., fred_category for browsing or fred_series_info for details). The description lacks explicit when-to-use or when-not-to-use conditions.

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, which fully cover safety. The description adds the list of returned metadata fields, which is useful context but not behavioral beyond what annotations provide. 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?

Two short sentences: first states purpose and output, second gives usage guidance. No wasted words, front-loaded with key information.

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

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

Given low complexity, 2 params, and presence of output schema, the description is complete. It lists expected return fields and provides usage context. No gaps.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description does not add any extra meaning beyond the schema, so 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 clearly states the verb 'Get' and the resource 'metadata for a series', listing specific fields. It distinguishes from siblings by implying metadata vs data (contrast with fred_get_series).

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

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

The phrase 'Check this before fetching historical data' provides clear usage context. While it does not explicitly name the sibling tool for data, the context strongly implies fred_get_series, and the instruction is direct.

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. The description adds details about fetching the page, extracting title/description/key links, and emitting markdown. No contradiction; behavior is well-disclosed.

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

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

The description is a single paragraph that front-loads the core action and purpose. It is informative without excessive verbosity, but could be slightly more structured (e.g., bullet points for use cases).

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 explains that the output is a 'single text blob' in llms.txt format. Parameters are fully covered by schema and description. Annotations cover safety. No gaps remain.

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% for both parameters. The description does not add significant new meaning beyond what is in the schema (e.g., 'Full URL' and 'default 25, max 50' are already present). Meets baseline.

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

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

The description clearly states the verb 'Generate' and resource 'llms.txt file for any URL', and distinguishes from siblings like 'ai_visibility_check' by focusing on file generation rather than audit. Use cases are explicitly listed.

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 clear context with use cases (client site indexing, own project, auditing competitor), but does not explicitly state when not to use or mention alternatives, leaving room for improvement.

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, indicating safe read. The description adds return field details and default active-only behavior, which complements annotations without 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?

Two concise sentences: first states purpose and return fields, second gives usage guidance. No extraneous words; information is front-loaded.

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

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

For a simple list tool with one optional parameter and thorough annotations, the description covers purpose, return fields, default behavior, and usage context. No gaps given 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 description coverage is 100%, and the schema already documents the parameter. The description adds context by clarifying default behavior ('active' subscriptions) and parameter purpose, but does not significantly exceed schema info.

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 'List the caller's active subscriptions' and enumerates returned fields. It distinguishes from siblings by explicitly mentioning use case 'review what you're monitoring before adding more or to find an id to cancel', which references subscribe and unsubscribe 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?

The description provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' It guides when to use (before subscribing/unsubscribing) but does not explicitly state when not to use or name 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?

The description goes well beyond annotations by disclosing rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token mechanism for no-account submissions, and the free/quota-free nature. It also explains how to check resolution status later. This is rich behavioral context over the simple annotation hints.

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

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

The description is front-loaded with purpose, then usage, exclusions, claim_token details, and rate limits. Every sentence earns its place, though it is slightly verbose with some redundancy (e.g., 'broken, missing, or needs to exist' plus category enumeration). Still, it remains focused 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?

Given the tool has no output schema and one nested parameter, the description provides essential context: purpose, scope, expected message content, rate limits, and the claim_token workflow. It could slightly improve by clarifying what happens when a user submits with an account, but the current detail is sufficient for correct use.

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 extra value by explaining claim_token usage in context ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), and by advising users to 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' This goes beyond the schema's per-parameter 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 clear, specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It distinguishes itself from sibling research/query tools by focusing on feedback for Pipeworx tools, and even scopes itself to only this connection's 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 guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is textbook usage 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, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: derived from CF analytics-engine, no PII, cached 5min-1h. 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?

Concise single paragraph with enumerated use cases. Every sentence provides essential information. No redundant or vague statements.

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 simple parameter set, rich annotations, and no output schema, the description fully covers what the tool does, its data source, caching behavior, privacy, and use cases. No gaps for an AI agent.

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

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

Only one parameter 'window' with enum. Schema description covers basic values; description adds semantic guidance: shorter windows surface hot trends, longer windows show steady-state demand. Adds meaningful 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?

Description explicitly states it returns 'top tools, top packs, and total call volume' over a specific window. Clearly distinguishes from sibling tools like ask_pipeworx and discover_tools by focusing on trending data from other agents.

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?

Lists three concrete use cases (discovering hot data, confirming canonical choice, aligning use case). Could explicitly mention when not to use (e.g., for specific factual queries use ask_pipeworx), but the guidance is clear and helpful.

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 (readOnlyHint, idempotentHint, etc.) already indicate safety. The description adds rich behavioral context: algorithmic details (monotonicity, partition checks), semantic anchor (Jaccard similarity), partition filter for placeholders, and fill check with realizable edge. It warns against trading when conditions aren't met. 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 verbose, diving into detailed algorithmic explanations (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). While well-structured with mode-first presentation, it could be more concise by omitting implementation details that may not be necessary for tool selection. Every sentence adds value, but the length may hinder quick parsing.

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 explains the response structure (opportunities[] with fields, partition_check details, fill_check). It references sibling tools for related functionality (polymarket_fill_risk for custom sizing). Given the tool's complexity (idempotent, non-destructive, two optional params), the description is comprehensive enough for an agent to understand input, output, and usage contexts.

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?

Both parameters (event, topic) have schema descriptions, but the tool description adds substantial value: explains the difference between single-event and cross-event modes, gives example inputs ('fed-decision-may-2026', 'Strait of Hormuz...'), and describes internal logic (Jaccard similarity, placeholder filtering). This far exceeds the schema's basic 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 clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes between three modes (no args, event, topic) with specific use cases, making it easy to differentiate from sibling tools like polymarket_edges or polymarket_fill_risk.

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 for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It explains when to use each and contrasts cross-event vs single-event detection. Provides examples of valid inputs (e.g., 'fed-decision-may-2026'). No when-not-to-use, but the positive guidance is clear.

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

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

The description discloses extensive behavioral details beyond annotations, including the three model families, caching at 1h, response structure, tradeable-edge knobs, and even the fact that partition arbs always return kelly_fraction_half=0 at the parent level. It also explains diagnostics so callers can understand why segments are empty. Annotations already indicate readOnlyHint, so 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 long but well-structured with bolded sections and clear groupings. Every sentence adds value, and the front-loaded purpose sentence is clear. However, the length is considerable and could be trimmed slightly without losing information, so it is not maximally concise.

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 complexity (three model families, many parameters, no output schema), the description fully covers the response structure, diagnostic fields, caching behavior, and the tradeable-edge knobs. It explains even edge cases like Fed bets and why partition arbs have different Kelly behavior. This is complete enough for an agent to use 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?

With 100% schema coverage, the description adds significant meaning beyond the schema. It explains the rationale behind default values (e.g., slippage_pp describes typical Polymarket fees), how knobs interact (e.g., min_partition_leg_kelly vs min_kelly), and provides practical tuning advice (e.g., bump slippage for thin partitions). This is exemplary parameter documentation.

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 scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, tailored for 'what should I bet on today'. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, so differentiation is inferred but not explicit.

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

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

The description provides clear context for when the tool is useful (discovering opportunities without paging through markets) and includes detailed guidance on parameter knobs and their effects. It does not explicitly state when not to use this tool versus alternatives, but the extensive parameter explanations offer implicit usage boundaries.

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 provide safety hints; description adds valuable behavioral context: history bounded by 60-day TTL, snapshots written on cache-miss, decay from daily closes not intraday. 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?

Dense but well-structured: problem statement, args, response sections. Slightly long but every sentence earns its place with specific value.

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 2 params, no output schema, and high complexity, the description is very complete: explains output fields, limits (TTL, cache-miss), and behavior (decay computation). No gaps.

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

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

Schema coverage is 100%, but the description adds meaning: defaults (days=14, window='1wk'), clamp (days 2-30), and explains output structure in detail (tracked[], expired[], snapshot_dates[]). Compensates for lack of output 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 answers 'how long has this edge existed and is it shrinking?' and enumerates the output fields (tracked[], expired[], snapshot_dates[]), distinguishing it from sibling polymarket_edges which likely provides current edges.

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

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

The description implies use for assessing edge persistence vs freshness ('a fresh wide edge and a 3-week-old wide edge are different trades'), but does not explicitly state when not to use or list alternative tools.

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

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

Annotations declare the tool as read-only, open-world, idempotent, and non-destructive. The description enriches this by detailing specific behaviors: walks the order-book ladder, returns top_of_book, vwap_fill_price, slippage_pp, verdict, and for baskets, per-leg fill detail, thin_legs, and forced directional risk warnings. No contradictions; it adds substantial behavioral context.

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

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

The description is very long and dense, combining all information into a single paragraph without clear visual separation. While it is logically structured (purpose, modes, details, usage advice), it could be more concise and easier to scan quickly for an AI agent.

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 thoroughly enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and explains the risk of partial basket fills. It addresses all key aspects needed for an agent to understand the tool's behavior and output.

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 significant extra meaning: it clarifies the dual-mode parameter requirements (market vs event), explains the side default logic for baskets (auto based on partition sum), and describes the interpretation of size_usd in each mode (max spend vs target proceeds vs settlement notional). It also notes clamping bounds (10–1,000,000).

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth', with explicit single-market and basket modes. It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by referring to them and specifying when to use this tool before acting on their signals.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains the rationale—theoretical overround on thin books is not capturable and partial fills create directional risk—providing clear context for appropriate usage.

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 give readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral details: compatibility_warning causes, temporal alignment flag, skipped_cross counters, and leg-by-leg price comparison. 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?

Though lengthy, every sentence is meaningful. Structured with clear sections (modes, response, safety fields, temporal alignment) and 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?

No output schema, but description covers response structure (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, counters). Handles edge cases like semantic mismatch and temporal gap. Complete for a complex dual-venue 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 has 100% description coverage with examples. The description re-explains parameter roles (topic vs explicit, overrides) but doesn't add new syntax. Baseline 3, plus modest extra context justifies 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 the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself by explaining two modes (topic shortcuts and explicit tickers) and contrasts with sibling tools like polymarket_arbitrage.

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?

Guidance is explicit: use `topic` for 10 pre-mapped macros, or explicit tickers for custom pairings. It warns that most topics return compatibility_warning, and provides conditions for meaningful spreads (matched pairs, temporal alignment).

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping detail (by identifier), which is useful beyond 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?

Three concise sentences, each adding value: main action, usage context, and pairing. No wasted words.

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

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

For a simple retrieval tool with one optional param and no output schema needed, the description fully covers purpose, scoping, and usage. Complete.

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

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

Schema coverage is 100%, schema description already says 'omit to list all keys'. Description repeats this but adds no new detail about the parameter format or 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?

Clearly states verb 'retrieve' and resource 'value', distinguishes from siblings 'remember' and 'forget', and covers the optional listing behavior.

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

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

Explicitly says when to use (look up stored context) and how to pair with remember/forget. Does not explicitly state when not to use, but implies retrieval context well.

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 indicate readOnly, idempotent, and non-destructive. The description adds behavioral details: return structure, the effect of mark_read on subsequent calls, and that polling works fine. 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?

Four sentences, each serving a distinct purpose: purpose, parameter details, mark_read behavior, alternative access. No redundant text. Ideal length.

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

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

All parameters are covered in schema and description. Return values are described (source, citation_uri, raw payload). Alternative access method is provided. For a read-only tool with no output schema, this is complete.

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

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

Schema coverage is 100% with good descriptions. The description adds value by giving an example for type ('sec_8k'), clarifying 'since' as ISO timestamp, and explaining the side effect of mark_read. This 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 clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It details what each event carries (source, citation_uri, raw payload), distinguishing it from sibling tools like list_subscriptions or recent_changes.

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

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

The description explains when to use (pulling alerts), how to filter by type and since, and the effect of mark_read. It also mentions an alternative REST endpoint for scripts/dashboards, but does not explicitly contrast with sibling tools.

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

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

Annotations already indicate safe read operation; description adds detailed behavioral context: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO soft-fail, and returns grouped changes with citation URIs.

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?

Compact, well-structured description with front-loaded examples, parameter details, fallback behavior, and sibling distinction, all in a few sentences 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?

No output schema, but description fully explains return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs) and covers error states like patent soft-fail. Complete for a 3-param 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?

100% schema coverage is high, but description adds value by explaining accepted formats for 'since' (ISO date or relative shorthand), suggesting typical values, and clarifying that 'value' accepts ticker or CIK.

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 a 'change feed for a company in the last N days/weeks/months' from multiple sources, with specific query examples distinguishing it from sibling tools like entity_profile.

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 provides usage contexts with example queries and contrasts with entity_profile ('Use entity_profile instead when you want the static profile...'), plus describes fallback behavior between GDELT and GNews.

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 scoping by identifier, persistence differences for authenticated vs. anonymous users (24-hour expiration), and complements the annotations (idempotentHint, destructiveHint). 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?

Two well-structured sentences front-load the purpose, then provide usage guidance and behavioral details. No wasted words.

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

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

For a simple two-parameter tool with no output schema, the description fully covers usage, behavior, and retention policies. Annotations handle the safety profile.

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 examples. The description adds value by explaining scoping and persistence, but the parameter meaning is already clear from the schema.

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

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

The description clearly states the tool's purpose: save data for later reuse across conversations or sessions. It provides concrete examples and distinguishes it from sibling tools 'recall' and 'forget'.

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 when you discover something worth carrying forward' and mentions pairing with recall and forget, giving clear guidance on when to use and 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?

Beyond the annotations (readOnly, idempotent), the description discloses that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, that LEI/FIGI enrichment degrades gracefully if GLEIF/OpenFIGI is unavailable, and that each call cascades through multiple lookup endpoints. These behavioral traits add substantial context and transparency.

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 lengthy but well-structured, opening with concrete user intents, followed by a concise functional statement, and then detailed per-type behavior. While every sentence adds value, the density is high and could benefit from tighter formatting or bullet points for easier scanning.

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

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

Given the tool's complexity, the description is remarkably complete: it covers purpose, usage timing, parameter specifics, edge cases (unresolved identifiers, graceful degradation), and the relationship to other tools. It even preempts questions about return values by naming the identifiers returned, effectively substituting for an output schema.

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

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

Although the schema already provides descriptions for both parameters (100% coverage), the description adds deep meaning by detailing what each type returns: for 'company' it lists CIK, ticker, LEI, parent/ultimate-parent/children ownership, and FIGI; for 'drug' it lists RxCUI, ingredient, and brand. Concrete examples for 'value' (ticker, CIK, name; brand/generic drug names) further enrich the parameter semantics.

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 a user-spoken name to canonical/official identifiers, with specific examples like 'What's the ticker for…' and 'find the CIK for…'. It distinguishes itself from sibling tools by noting these identifiers are required as input by other tools and explicitly instructs to 'Use FIRST whenever you have a name but need an ID.'

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

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

The description explicitly states when to use the tool ('Use FIRST whenever you have a name but need an ID'), and clarifies the supported types (company/drug) with details. It also explains that using resolve_entity replaces 2-3 manual lookups, providing clear context for choosing this tool over alternative manual processes.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds that it internally probes each entity with 'ai_visibility_check', ranks by score, and returns a list with score, confidence, signal density. No contradictions; it provides useful behavioral context beyond 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, front-loaded with the primary action, then explains the process, use case, and output. No redundant or irrelevant information; 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?

Given 4 parameters (100% schema coverage) and no output schema, the description explains the tool's operation (calling ai_visibility_check, ranking, output fields). It is sufficient for an AI agent to understand what the tool does and what it returns, though it could be more detailed on output semantics or error handling.

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

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

Schema description coverage is 100%, so all parameters have descriptions. The description adds semantic value by clarifying that the first entity in 'entities' is treated as the 'subject' for narrative. This goes beyond the schema definition, aiding correct parameter usage.

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 compares AI visibility across multiple entities side-by-side, uses 'ai_visibility_check' per entity, ranks results, and surfaces most/least recognized. It distinguishes from sibling 'ai_visibility_check' (single entity) by emphasizing multi-entity 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 explicitly gives a use case (competitive AI-marketing audits) and an example question. It implies when to use: for comparing multiple entities. It does not explicitly state when not to use or name alternative tools, but the context is clear enough.

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

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

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds important behavioral details: bundlephobia's first measurement can take 5-30 seconds, partial failures degrade gracefully (sources_failed lists timeouts), and the NPM-only scope. Additional context beyond 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 detailed yet well-structured, front-loading the composite nature and usage. Every sentence adds value (output fields, ecosystem note, behavioral caveat). Slightly longer than necessary but efficiently packed.

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

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

Given no output schema, the description lists the return fields (summary block, per-advisory detail, links, alternatives) and covers edge cases (scoped packages, version default, partial failures). For a tool with two parameters and complex output, this is reasonably complete.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds minor context: scoped packages are accepted and version defaults to latest, but does not significantly augment the schema's meaning. 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 purpose as a composite safety/quality check for npm packages, covering license, advisories, version history, and bundle analytics. It distinguishes from siblings by noting that other ecosystems like PyPI, Maven, etc., fall under deps.dev:version.

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 when to use the tool: when an agent asks about safety, popularity, size, or cost of adding an npm package. Also provides exclusion guidance for other ecosystems, referencing an alternative.

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 indicate read-only, idempotent, open-world, non-destructive behavior. Description adds technical details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation flag, and output includes offsets and similarity scores. Contradicts nothing.

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 well-structured sentences: purpose, use case/benefit, technical details and pairing. No unnecessary words, front-loaded with key information.

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

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

Given no output schema, the description adequately covers outputs (passages with offsets and scores) and limitations (200K char cap, truncation flag). Also mentions pairing with a sibling tool. Comprehensive 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% with parameter descriptions. Description adds context by explaining that limit controls 'top-N passages' and that query is a natural-language question with examples, slightly enriching the schema. Baseline 3, slight improvement gives 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?

Clearly states it performs semantic search inside a fetched record, distinguishing it from sibling tools like ask_pipeworx and ask_pipeworx_grounded. Specifies input (text and query) and output (top-N passages with offsets and scores).

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 advises use when the record is too large for the prompt, and pairs with ask_pipeworx_grounded for grounded generation. Provides a concrete use case and benefit (saves context, enables verification).

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 indicate readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds important behavioral details: OAuth requirement, delivery channel limits (10/day SMS cap), webhook auto-disable after 10 failures, and phone verification need. No contradictions 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 somewhat long but efficiently packed with examples and constraints. It front-loads the core purpose and action, then organizes types and delivery details. Every sentence adds essential information without 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?

Given the tool's complexity (3 params, nested objects, multiple types and delivery options) and lack of output schema, the description is very complete. It covers prerequisites, type-specific parameters, delivery channels with constraints, and the return value. No significant gaps.

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

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

Schema coverage is 100%, but the description adds significant value with concrete examples (e.g., sec_8k items, polysmarket_edge topic) and explains delivery constraints beyond schema descriptions. It clarifies required vs optional fields in params and delivery.

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

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

The description clearly states the verb 'Create' and the resource 'proactive monitoring subscription to a live-data event stream', and specifies it returns the subscription ID. It distinguishes itself from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation of new 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 explicitly requires a Pipeworx OAuth account and states that anonymous/BYO users cannot persist subscriptions. It provides context on when to use each type (e.g., sec_8k for filings) and delivery constraints (phone verification, SMS cap). It could be improved by more direct contrast with alternatives like recent_alerts or validate_claim.

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, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context beyond annotations: it describes the return format (category-bucketed example questions with tool+argument shapes) and that it draws from a live catalog.

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?

Well-structured with front-loaded example queries and a clear list of categories. Every sentence adds value, though slightly verbose. It 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?

With one optional parameter, no output schema, and annotations covering safety, the description fully explains what the tool does and returns (category-bucketed questions). No gaps.

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

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

Schema coverage is 100% with one optional parameter. The description explains the valid values for topic and what happens when omitted (full spread). This adds meaning beyond the schema's description.

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

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

The description clearly states it is the onboarding entry point, listing example queries and explaining that it returns category-bucketed example questions with exact tool+argument shapes. It distinguishes itself from siblings by being the 'first' thing to call when you don't know what Pipeworx can do.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' The optional topic parameter is explained. It lacks explicit when-not-to-use, but the context strongly implies usage.

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 (idempotentHint=true, destructiveHint=false), the description adds critical details: ownership enforcement, deactivation vs deletion, and that historical events remain viewable via recent_alerts. 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?

Two sentences delivering all essential information in a direct, front-loaded manner. 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?

Given the simple tool (1 parameter, no output schema, rich annotations), the description fully covers purpose, constraints, side effects, and relationship to other tools (recent_alerts). No gaps.

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

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

Schema coverage is 100% with a clear description of the 'id' parameter. The tool description does not add additional semantics beyond what the schema already provides, so baseline score 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 action ('Cancel a subscription by id'), the specific context ('Ownership is enforced'), and the behavioral nuance ('row is deactivated, not deleted'). It distinguishes from sibling tools like subscribe and list_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 implies when to use (after subscribing, to cancel) but does not explicitly state when not to use, such as if permanent deletion is desired or if the subscription is not owned by the caller.

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 (read-only, open-world, idempotent), the description discloses critical behavioral nuances: the exact meaning of the 'could_not_verify' verdict, that it is NOT evidence for or against a claim and should never be presented as such, and the distinction from 'unsupported'. It also explains the structured fast path (SEC EDGAR + XBRL with exact percent-delta math) versus the grounded fallback, which is valuable context 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?

The description is longer than minimal, but it is front-loaded with trigger phrases and then follows a logical structure: purpose, two-path explanation, return format, caller warning, and value proposition. Every sentence carries distinct information; the 'IMPORTANT for callers' section is essential and not filler. It earns a 4 rather than a 5 because the trigger phrase list and some redundancy could be trimmed 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?

Given the tool's complexity (multiple verdict types, failure semantics, dual routing paths, no output schema), the description is remarkably complete. It explains what the tool returns (verdict, grounded or structured actual value, citation, reasoning), clarifies the critical could_not_verify behavior, and ties in the replacement of a multi-step workflow. It provides enough context for an agent to select and invoke the tool appropriately without needing to see the output schema.

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

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

Schema description coverage is 100%, and both parameters ('claim' and 'tolerance_pct') are thoroughly documented in the input schema, including examples, defaults, and overriding behavior. The description itself adds little beyond what the schema already provides, so the baseline of 3 applies — the schema carries the semantic load adequately.

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 concrete trigger phrases ('Is it true that...', 'fact check', 'verify the claim that...') that make the tool's scope unmistakable. It names the specific resource (natural-language claims) and the core action (verification against authoritative sources), and clearly distinguishes it from siblings like deep_research or ask_pipeworx by describing its two execution paths and direct verdict outputs.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also differentiates the routing logic for company-financial claims versus any other factual claim, and notes that it replaces 4–6 sequential calls, giving the agent a clear reason to prefer this tool over composing a chain manually.

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