Coresignal

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

The description adds behavioral context beyond annotations: it specifies the default model (Workers AI Llama-3.3-70b, free), the need for an API key to probe Anthropic (BYO key, user pays), and the return structure (per-model {score, confidence, signals, raw_response} + combined view). Annotations already indicate readOnlyHint=true and idempotentHint=true, so the description complements them well.

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

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

The description is two sentences, front-loaded with the core action and scoring. Every sentence adds value: first sentence states the purpose and outcome, second sentence covers defaults, authentication, and return structure. 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 has 4 parameters (all described in schema and enriched in description), no output schema but the description specifies the return format, and annotations cover safety, the description is sufficient for an agent to use the tool correctly. It explains the probing mechanism, costs, and typical use cases.

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

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

Schema coverage is 100%, but the description adds meaning beyond the schema. For example, for 'models' it explains the supported values and default. For '_apiKey' it clarifies it's optional and passed to Anthropic. For 'context' it provides an example. The description enriches parameter understanding.

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

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

The description clearly states the tool's function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' It uses specific verbs and resources, and the sibling context shows this tool is distinct from similar tools like scan_competitor_ai_presence.

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

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

The description provides clear usage context: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It explains the default model and the need for an API key for Anthropic. However, it does not explicitly state when not to use the tool or mention alternatives, so it's not a perfect 5.

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

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

Annotations already declare safe read-only, idempotent behavior. Description adds valuable context: routing to 5,529 tools, filling arguments, returning citation URIs, and working on every tier. Does not contradict annotations; some extra context (rate limits, failure modes) is omitted but not expected for a read-only router.

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 lengthy but each sentence carries useful guidance: domain coverage, usage examples, alternatives, and formatting. It is front-loaded with the key 'prefer over web search' instruction. Could be slightly more structured with bullets, but the density is justified for a default router tool.

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 broad scope, the description is remarkably complete: it covers domain coverage, trigger phrases, examples, output format, performance characteristics, tier availability, and clear alternatives. No output schema exists, yet the description clearly states what the user gets (structured answer with 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?

Input schema covers all six parameters (aliases for 'question') with 100% description coverage. The description adds examples of good questions but does not explain parameter syntax or behavior beyond what the schema states. No additional parameter semantics needed.

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

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

The description clearly states the tool's function: routing factual questions to the appropriate specialized tool and returning structured answers with citations. It distinguishes from siblings by naming alternative tools (ask_pipeworx_grounded, deep_research) and explicitly framing itself as the default entry point.

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

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

Gives explicit when-to-use guidance: prefer over web search for a comprehensive list of domains, use for common factual query phrasings, and provides concrete examples. Also provides escalation paths for alternative tools, covering both when and when-not logic.

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, the description explains the beta behavior, the live candidate routing improvements, the current inactivity (matching ask_pipeworx exactly), and that results are compared to the stable router. This adds meaningful context about how the tool operates at runtime.

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 composed of four sentences that each carry distinct information: identity/equivalence, current state, usage guidance, and the clarification that it is a full router. It is moderately concise and front-loaded with the most important facts.

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 is a beta router without an output schema, the description sufficiently covers its role, current behavior, and usage. It points to ask_pipeworx for exact response shape and arguments, which is adequate since that sibling is listed. A minor gap is the lack of a direct explanation of what the router returns, but annotations and schema cover safety and input semantics.

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

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

The schema already fully describes all parameters (100% coverage) as aliases for the natural-language 'question'. The description adds no new parameter meaning beyond saying the tool takes the same arguments as ask_pipeworx, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, a universal router with 5,529 tools, and distinguishes it from the stable ask_pipeworx sibling via its experimental nature. It also states the tool is currently identical to ask_pipeworx, removing ambiguity.

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 to use the tool when you want the newest routing, and implies the stable ask_pipeworx as the alternative for non-experimental use. It also clarifies that this is a full working router with no fallback, but it doesn't explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral detail: the exact response envelope ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}), the explicit refusal reasons enum, the guarantee to use ONLY tool result content, and the one-extra-LLM-call cost. It doesn't describe pagination or rate limits, but for a read-only, idempotent, grounded-answer tool, this is strong behavioral 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 a single dense paragraph front-loaded with the core value proposition ('Hallucination-resistant answer mode for high-stakes reads'), followed by routing mechanics, output shape, refusal reasons, and usage guidance. It's longer than two sentences but each clause earns its place by adding specific behavioral or usage detail. Slightly dense but well-structured and not wasteful.

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?

This tool has no output schema, so the description correctly compensates by fully specifying the return shape and the refusal_reason enum values. Annotations provide safety context (read-only, idempotent, open-world). The comparison against ask_pipeworx, including the extra LLM call cost, gives the agent enough context to decide whether to use it. For a tool with a single free-text parameter and no output schema, the description 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 description coverage is 100% (all 6 parameters are aliases for the question with a clear description on 'question'), so the schema already carries the parameter semantics. The description adds the context that the question is in natural language and that the tool 'fills arguments' internally, but it doesn't need to detail the parameters because the schema is explicit. Baseline 3 is appropriate.

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

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

The description states a specific verb ('answer mode') and resource ('Pipeworx'), and clearly distinguishes it from sibling ask_pipeworx by emphasizing hallucination resistance and evidence extraction. It explicitly contrasts with 'same routing as ask_pipeworx' while adding a unique guarantee, so it differentiates from siblings.

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

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

Provides explicit when-to-use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and lists concrete use cases. Also gives exclusion guidance: 'prefer ask_pipeworx for casual lookups' and mentions the extra LLM call cost as a trade-off, which effectively tells the agent when not to use it.

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

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

Annotations already indicate safe, idempotent, read-only behavior. Description adds extensive details: fan-out logic, resolver contract, parent event extractor, news fallback, safety short-circuits, wide-spread checks, and cancellation rule parsing. 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?

Description is lengthy but front-loaded with main purpose. Extensive detail is justified by tool complexity. Could be slightly more concise, but structure is logical.

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

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

No output schema exists, so description covers all return shapes thoroughly (result.market, analysis, evidence, resolver contract, parent event, news fields). Covers blocking conditions, edge cases, and resolution risks. Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for all three parameters. Description adds value by explaining market parameter formats, providing examples, and clarifying depth and include_raw defaults.

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 researches Polymarket bets by pulling Pipeworx data. It specifies input formats (slug, URL, question text) and output (evidence packet + comparison). It distinguishes itself from siblings like polymarket_arbitrage by its unique research focus.

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

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

Explicit usage scenarios provided ('should I bet on X', 'what does the data say about Y'). Includes classifiers and fan-out examples. Does not explicitly exclude cases or mention sibling alternatives, but context is sufficient for an agent.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, result sorting by primary metric, and return of citation URIs. 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?

Description is a single paragraph front-loaded with common use-case phrases. It is efficient (5 sentences, 83 words) and every sentence adds value. Could be slightly more structured (e.g., bullet points) but is not overly verbose.

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, description covers return format (paired data + citation URIs), behavior (sorted by primary metric), and replaces many lookups. It is complete for the tool's complexity.

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

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

Schema has 100% coverage. Description adds meaning beyond schema: explains what each enum value pulls (company vs drug data), gives examples for values (tickers/CIKs for company, names for drug), and specifies min/max items.

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 does side-by-side comparison of 2-5 companies or drugs, with specific trigger phrases. It distinguishes from sequential single-pack lookups by explicitly recommending this tool over them, and mentions it replaces 8-15 lookups.

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 guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It implies when not to use (not for single lookups) and gives examples of when to use (comparing companies or drugs).

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 context about the data source (LinkedIn-adjacent B2B data) and the fields returned (size, employee count, industry, etc.), which is useful beyond annotations. It 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 plus a concise example. Front-loaded with purpose. Every sentence adds value (purpose, parameters, example data). No extraneous content.

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

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

Despite lacking an output schema, the description lists the key return fields (firmographics, headcount, industry, founding year, HQ, LinkedIn URL), which is sufficient for a simple lookup tool. Annotations provide safety guarantees. 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% (all three parameters described in schema). The description restates the name and website parameters and provides an example, but adds no new semantic information beyond what the schema already conveys. 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 'Look up a company's firmographics + headcount' from Coresignal by name or website, specifying the action and resource. It distinguishes itself from the sibling tool 'coresignal_employee' which focuses on employee lookup.

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 indicates when to use the tool (by company name or website) and provides an example call. However, it does not explicitly state when not to use it or compare to alternatives like 'coresignal_employee' or other lookup tools, leaving some inference to the agent.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. Description adds specifics about returned data (title, company, location, LinkedIn URL, experience, education) and notes it's 'LinkedIn-adjacent', providing useful 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?

Two sentences plus an example, front-loaded with purpose. No unnecessary 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?

While no output schema exists, the description lists returned fields and provides an example. It covers the main aspects for a simple lookup, though pagination and error handling are omitted.

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 all parameters (100% coverage). The description adds an example call showing usage, but does not add extra semantic meaning beyond what the schema provides.

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

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

The description clearly states the tool finds a person's professional profile by name and optionally company, listing returned fields. However, it does not differentiate from siblings like entity_profile or 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?

No guidance on when to use this tool versus alternatives such as coresignal_company or other people discovery tools. The description only states what it does, not the best context for 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?

Adds rich behavioral detail beyond annotations: explains the findings packet structure (verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[] for unanswered facets, contradictions[], semantic excerpting, hop field, citation_uri fetchability, and timing expectations. Also discloses account and paid-tier requirements, which annotations do not cover.

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 every sentence adds value, front-loaded with the account requirement and core purpose. It is dense and packed with details, though it could be slightly restructured into bullets for readability. Length is justified given the tool's complexity.

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

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

Despite having no output schema, the description fully explains what is returned: findings packet contents, gaps[], contradictions[], citation_uri, hop field, and semantic excerpting. It also covers account prerequisites, runtime expectations, and alternative tools, making it complete and actionable.

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 describes both parameters, the description adds significant semantics: depth variants ('quick'=3 facets, 'standard'=gap recovery + contradictions, 'thorough'=paid with iterative leads) and that question should be natural language and can be broad/multi-part. This goes well beyond the schema's enum 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?

Clearly states it performs grounded multi-source research across 1455 structured data sources, decomposing questions into facets and routing to 5,529 tools in parallel. It explicitly says 'this is NOT open-web search' and distinguishes itself from ask_pipeworx, making its purpose and scope 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?

Provides explicit when-to-use guidance and alternatives: 'If you are not signed in, use ask_pipeworx instead,' 'For a single lookup use ask_pipeworx,' 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx,' and 'Best for broad/multi-part questions over structured data.' This fully clarifies when this tool should be selected over siblings.

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=true and idempotentHint=true, and the description adds rich behavioral detail: returns top-N tools with names, descriptions, and full input schemas with curated examples, ready to call directly. No contradiction with annotations. Fully transparent about output behavior and usage 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 well-structured with a front-loaded purpose statement, followed by usage guidance and behavioral details. It is 7 sentences long, each earning its place, though the list of data sources could be slightly more concise without losing meaning.

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

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

Despite lacking an output schema, the description clearly explains what is returned (tool names, descriptions, schemas, examples). It provides comprehensive context for a discovery tool with 6 parameters, all documented, and gives explicit calling guidance. 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% so the schema fully documents all 6 parameters. The description adds context by listing example data domains and mentioning aliases (task, q, description, search), but this adds only marginal value over the schema's parameter descriptions. Baseline 3.

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

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

The description states 'Find tools by describing the data or task' with a specific verb and resource. It clearly distinguishes from sibling tools (e.g., search_within, bet_research) by being the meta-tool for discovering other tools, not for directly querying data.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides context for when to use (browse, search, discover) but does not explicitly state when not to use or name alternatives, though the sibling list implies alternatives for specific tasks.

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, open-world, idempotent, non-destructive. Description adds behavioral details beyond annotations: explains soft-fail for patents, up to 5 recent filings, GDELT→GNews fallback, and return structure. 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?

Front-loaded with example queries, then lists sources and fields. Every sentence adds value, though slightly long. Could be more concise but not wasteful.

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, so description bears full burden. Thoroughly explains return fields (cik, company_name, recent_filings with URIs, fundamentals sorted, patents, news, LEI) and their sources. Covers all relevant context for a complex tool.

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

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

Schema coverage is 100% with descriptions, so baseline is 3. Description adds significant value: clarifies name not supported, explains ticker vs. zero-padded CIK format, and gives examples. Slightly above 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?

Clearly describes the tool as returning a full cross-source profile of a US public company, listing specific data sources and fields. Distinguishes from siblings like 'resolve_entity' and 'compare_entities' by mentioning 'holistic view' and noting name vs. ticker/CIK input.

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

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

Explicitly states when to use: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also gives clear exclusion: names not supported, recommends 'resolve_entity' first if only a name is available.

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 readOnlyHint=false. The description adds context about clearing 'sensitive data', which provides practical behavioral insight beyond the annotations. No contradictions.

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

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

The description is extremely concise (two sentences) with the purpose front-loaded. Every sentence adds value 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?

For a simple tool with one required parameter and no output schema, the description fully covers purpose, usage, and relationships to sibling tools. It is complete and actionable.

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

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

Schema coverage is 100%, and the description does not add additional meaning beyond what the schema already provides for the 'key' parameter. 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') and the resource ('a previously stored memory by key'). It explicitly differentiates from sibling tools 'remember' and 'recall' by indicating it performs deletion.

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 specific scenarios for use: 'when context is stale, the task is done, or you want to clear sensitive data'. It also directs the agent to pair with 'remember' and 'recall', offering clear guidance on when to use this tool versus alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds the behavioral context that it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions.

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

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

The description is a single paragraph with the core purpose in the first sentence, followed by additional details. It is efficient, front-loaded, and every sentence adds value 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?

With 2 parameters, no output schema, and comprehensive annotations, the description covers the process (fetch, extract, emit), output format (single text blob), and use cases. It is complete for the tool's simplicity.

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 value by explaining url as 'Full URL of the site to summarize' and max_links with default 25 and max 50, going beyond the schema.

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

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

The description clearly states the tool generates an llms.txt file for AI crawlers, specifying the action (generate), resource (llms.txt for a URL), and purpose (indexing). It distinguishes itself from the varied sibling tools, none of which have the same function.

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

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

The description lists explicit use cases: getting a client's site indexed, drafting for own project, or auditing competitors. While it does not mention when not to use it, the sibling list has no direct alternative, and the use cases are clear.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it lists active subscriptions and notes the include_inactive parameter, but does not disclose additional behavioral traits like pagination or rate limits. Adequate but not exceptional.

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

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

The description is two sentences, front-loaded with the core purpose, and every word adds value. No wasted 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 read-only list tool with one optional parameter and no output schema, the description is complete. It covers purpose, return fields, and usage context.

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

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

Schema coverage is 100% for the single parameter. The description mentions 'active subscriptions' implicitly referencing the default, but does not add meaning beyond the schema. 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 tool lists the caller's active subscriptions and enumerates the returned fields (id, type, params, etc.). It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

The description provides explicit guidance: use it to review current subscriptions before adding more or to find an id to cancel. It omits when not to use, 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?

Despite all annotations being false, the description discloses abundant behavioral traits: rate-limiting (5 per identifier per day), no quota impact, the claim_token round-trip mechanism, daily digest processing, and a content rule (don't paste end-user prompt). No contradiction with annotations.

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

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

The description is dense yet tightly structured: purpose first, then use cases, then scope exclusion, then workflow, then operational limits. Every sentence earns its place with no fluff, and it is appropriately sized for the tool's complexity.

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

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

Given the tool's complexity (feedback workflow, scope restrictions, rate limits) and no output schema, the description covers all necessary aspects: eligible scope, what to include/exclude, claim_token follow-up, rate limits, and expectations. It is fully actionable for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter semantics beyond the schema: it explains the claim_token usage pattern ('pipeworx_feedback({claim_token:"pwfb_…"})') and message length guidance, but this is largely redundant with schema descriptions. No significant added value.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes the tool from siblings by explicitly stating it is ONLY for tools served by this Pipeworx connection, not other MCP servers.

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 when-to-use guidance is provided for each feedback type (bug, feature/data_gap, praise). It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead,' plus a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists').

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds beyond these: data source (CF analytics-engine), privacy (no PII), data structure (pack, tool, count), and caching (5min-1h). This provides useful 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 four sentences with no wasted words. It front-loads the core functionality, then provides use cases, and finally technical details (source, privacy, caching). Every sentence serves a distinct purpose.

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

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

For a simple read tool with one optional parameter and no output schema, the description covers all essential information: what is returned (top tools, top packs, total call volume), caching behavior, privacy guarantees, and the meaning of the window parameter. The annotations cover safety and idempotency, making the description 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 one enum parameter ('window') that already has a description. The description adds semantic value by contrasting short windows ('hot right now') vs long windows ('steady-state demand'), helping the agent choose appropriately. No other parameters exist, so the description compensates 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 clearly states the tool returns top tools, top packs, and total call volume over a recent window. It uses a specific verb ('Returns') and identifies the resource ('trending data'). The tool's purpose is distinct from siblings, which include various research and entity tools but no other trending or analytics 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?

The description lists three explicit use cases (discovering hot data sources, confirming canonical tool, seeing alignment with agent needs). It does not mention when not to use or alternatives, but the use cases are clear enough to guide appropriate invocation. The sibling list has no competing trending tool, so exclusion is less critical.

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 (readOnly, idempotent, non-destructive) are consistent. The description adds rich behavioral details: semantic anchor, partition filter, fill check with depth pricing, and cross-event pairing logic. 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 lengthy but each sentence adds value and is well-organized. Slight verbosity in explaining internal checks could be streamlined, but it remains structured 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?

Despite no output schema, the description thoroughly covers response fields (opportunities, partition_check, fill check results), internal logic, and edge cases (low similarity, placeholders). Complete for a complex arbitrage tool.

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

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

Schema coverage is 100%, but the description adds meaning: explains event expects slug or URL, topic expects seed question, and details how each mode works, including internal algorithms.

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 via monotonicity violations and partition-sum checks. It specifies three modes (no args, event, topic) and distinguishes itself from sibling tools like 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: no args for trending scan, event for specific market, topic for cross-event scan. Also explains when not to trade (realizable edge <= 0) and references polymarket_fill_risk for custom sizing.

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

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

The description discloses caching behavior (1h at KV level keyed on all knobs), the structure of the response with diagnostics for empty segments, and why Fed bets are excluded. It aligns with annotations (readOnlyHint, openWorldHint, idempotentHint) and adds significant context beyond structured data.

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 verbose, packing technical details like model families and Kelly fractions. It is well-structured (purpose, segments, knobs, response), but could be shortened slightly without losing essential information. The complexity warrants the length.

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

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

Given the 9 parameters and no output schema, the description fully explains the response structure (by_segment, diagnostics, Fed note) and caching. It provides enough context for an agent to use the tool effectively without guessing.

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

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

Although schema coverage is 100%, the description enriches each parameter with practical guidance, e.g., slippage_pp explains zero fees but thin depth, and min_liquidity warns about walking the book. This adds value beyond the schema's field descriptions.

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

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

The description clearly defines the tool as scanning Polymarket markets for opportunities where Pipeworx data diverges from market price, specifically for 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage by focusing on disagreement-based signals rather than pure 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?

The description explicitly states the tool is for discovering opportunities without paging through many markets and explains when to use knobs like min_liquidity and max_spread_pp. It notes that Fed bets are excluded from ranking but present in the response. However, it does not explicitly compare to alternative tools like polymarket_fill_risk or polymarket_edge_tracker.

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 fully discloses behavior: it reads from daily snapshots, calculates time-series, trends, and decay. It also explains limits like TTL and snapshot gaps. This aligns with annotations (readOnlyHint, idempotentHint) and adds significant detail 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 concise yet comprehensive. It is structured with a purpose statement, argument details, response structure, and limits. Every sentence adds value with no redundancy or fluff.

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

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

Despite no output schema, the description thoroughly explains the response fields: tracked[], expired[], snapshot_dates[], including field meanings and limitations. It is complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context like 'snapshot family' and default values, and explains the meaning of 'window' in the context of the tool, providing slight additional semantics beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers a specific question and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series analysis of edge duration and decay.

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

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

The description provides context on when to use the tool ('how long has this edge existed and is it shrinking?') and why it matters (fresh vs old edges). However, it does not explicitly list alternative tools or scenarios where the tool should not be used, though the context 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?

Discloses extensive behavioral details: walks the order book ladder, returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; for basket mode returns theoretical_sum, realizable_sum, capture_ratio, profit_usd, per-leg details, thin_legs, max_clean_notional_usd, forced_directional_risk. Warns about partial fills converting arb into unhedged positions. No annotation contradiction (annotations indicate readOnly, idempotent, non-destructive – consistent).

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

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

The description is dense but well-structured with clear sections (SINGLE-MARKET, BASKET) and uses uppercase for emphasis. Every sentence provides essential information—no wasted words. Despite length, it avoids redundancy and is front-loaded with the core purpose.

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

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

Given no output schema, the description fully covers return values for both modes, parameter interactions, and risk context. It explains the verdict (clean|degraded|cannot_fill) and the forced_directional_risk field, making the tool self-contained for an AI agent. The complexity of the tool (two modes, multiple outputs) is fully addressed.

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 description adds significant extra meaning: for size_usd it explains 'max spend on buys, target proceeds on sells' (single-market) and 'settlement notional — shares per leg, each paying $1 at resolution' (basket); for side it clarifies defaults in both modes. This goes well beyond the schema's short 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 it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket/partition), with specific verbs and resources. It differentiates from sibling tools like polymarket_arbitrage and polymarket_edges by stating when to use this tool before those.

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 states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround not capturable, partial fills create directional risk). It also notes that one of `market` or `event` is required, providing clear context for when and 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?

The description goes far beyond the readOnlyHint, openWorldHint, and idempotentHint annotations by detailing safety fields, temporal alignment, skipped cross types, and precise conditions for spreads being meaningful.

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

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

The description is thorough but somewhat verbose. It uses structured sections with bold labels and bullet points, which aids readability, but could be trimmed slightly without losing 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 the complexity (two modes, cross-venue matching, temporal alignment, safety fields) and no output schema, the description is remarkably complete. It explains how to interpret response fields and what each safety metric means.

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 examples for topic values and explicit tickers/slugs, and explains the auto-override logic, adding 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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question, with two modes. It distinguishes from sibling tools like polymarket_arbitrage (single-venue) and polymarket_edges (single-venue).

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 topic mode (pre-mapped macro shortcuts) vs explicit mode, and warns that most pre-mapped topics return a compatibility warning, implying they are not tradeable. It does not explicitly list when not to use, but sibling tool names provide alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable context about scoping to an identifier and the behavior of omitting the key argument, which is not covered by annotations.

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

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

The description is concise at three sentences, front-loaded with the core function, and every sentence adds value without any 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 simplicity of the tool (one optional parameter, no output schema, comprehensive annotations), the description covers all necessary aspects: retrieval behavior, listing, scoping, and pairing with other tools. It is fully 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?

The schema already describes the `key` parameter with 100% coverage. The description adds meaning by explaining the effect of omitting the key and further elaborating on usage, thus adding value 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 that the tool retrieves a value saved via remember or lists all keys if no argument is given. It uses specific verbs and resource, and distinguishes itself from sibling tools like remember 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 provides clear use cases (looking up stored context) and mentions pairing with remember and forget. It implies when to use but could be more explicit about when not to use compared to other tools.

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

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

Annotations already declare readOnlyHint and destructiveHint. The description adds behavioral details such as the effect of mark_read and the alternative endpoint, but does not deeply expand 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 concise, front-loaded with the main purpose, and includes useful examples without unnecessary 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 and thorough annotations, the description covers all necessary aspects: what is returned, filtering options, read-tracking behavior, and alternative access.

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 value by providing example filter values (e.g., 'sec_8k') and clarifying how mark_read affects subsequent calls.

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 retrieves recent alerts from the subscription feed, specifying returned fields. While no explicit comparison to siblings, the purpose is specific and unambiguous.

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

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

The description mentions that polling works fine and provides an alternative REST endpoint, but does not explicitly state when to use this tool versus alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds valuable behavior: fans out to multiple sources, soft-fails for patents, fallback logic. 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?

Description is front-loaded with examples. Each sentence adds value, though slightly verbose. No wasted words, but could be trimmed minutely.

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 (multiple sources, fallback, soft-fail) and no output schema, description adequately explains return structure (changes grouped by source, total count, citation URIs). Complete for the tool's purpose.

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 description adds examples (ISO vs relative shorthand) and suggests default value ('30d' or '1m'). Also explains that value can be ticker or CIK, beyond schema text.

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 across multiple sources (SEC, GDELT/GNews, USPTO) within a time window. It distinguishes from sibling entity_profile by specifying when to use the latter. The verb 'change feed' and resource 'company' are specific.

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 mentions when to use entity_profile instead, gives query examples, and describes fallback behavior (GDELT to GNews). Provides context on date formatting and typical monitoring recommendation.

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?

Describes persistence behavior (authenticated vs anonymous) and scoping, adding value beyond annotations that only indicate idempotentHint=true.

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 and well-structured; each sentence adds useful 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?

Complete information for this tool type: purpose, usage, parameters, pairing with siblings, and retention policy. No output schema needed.

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

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

Schema covers both parameters fully; description adds examples of keys and explains key-value pair concept, providing extra context 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?

Clearly states the tool's function: saving data for reuse across conversations/sessions. Distinguishes from siblings like recall and forget by mentioning pairing.

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 discovering something worth carrying forward, provides examples, and contrasts with recall and forget tools.

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

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

Beyond the annotations (read-only, idempotent, etc.), the description reveals important behaviors: graceful degradation when external sources are down, explicit listing of unresolved identifiers, source-labelling of every identifier, and internal cascade across multiple endpoints. This adds substantial 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 dense but well-organized, with examples, explicit type breakdowns, and important caveats. Every sentence contributes useful information, though length is slightly above average for a tool description.

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 adequately explains return behavior (identifiers, sources, unresolved list) and the multi-source internal processing. It covers input formats, supported types, and failure degradation, making it complete for a complex resolution tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the semantic difference between 'company' and 'drug', giving concrete input examples for 'value', and describing what identifiers are returned for each type. This goes beyond the schema's basic 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 clearly states the tool resolves user-spoken names to canonical identifiers with specific verbs ('resolve a user-spoken NAME to the canonical/official identifiers'). It distinguishes itself from siblings by emphasizing the lookup-to-ID role, and the examples illustrate the exact scenarios.

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 FIRST whenever you have a name but need an ID', giving clear when-to-use guidance. It does not explicitly mention alternatives or exclusions, but the strong recommendation implies priority over other tools.

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

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

Discloses key behaviors: probes each entity, ranks by score, returns score/confidence/signal density. Adds value beyond annotations which already mark it as read-only, idempotent, non-destructive.

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, directly informative, front-loaded with the core action. 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 tool with multiple parameters and no output schema, the description explains the return concept well (ranked list with metrics). Could be more precise about output structure, but 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 has 100% coverage, but description adds semantic value: clarifies that the first entity is the 'subject' for narrative meaning. Also explains the context parameter's purpose.

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

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

The description states exactly what it does: compare AI visibility across multiple entities, using ai_visibility_check internally, ranking results. It clearly distinguishes from the sibling ai_visibility_check which is for single entities.

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

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

Provides a clear use case ('competitive AI-marketing audits') and implies when to use it. However, it doesn't explicitly say when not to use or list alternatives beyond the existence of ai_visibility_check.

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 (readOnly, openWorld, idempotent, non-destructive), description details behavioral traits: fans out to multiple sources, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and failed sources are listed. This adds essential context not in structured data.

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 that packs a lot of information efficiently. It is mostly front-loaded with the composite nature. Could benefit from minor structuring (e.g., bullet points) for easier scanning, but current form is acceptable.

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 fully explains return components (summary, per-advisory, links, alternatives) and handles edge cases (partial failures, timeouts). For a 2-parameter tool, this is highly 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 both parameters described. Description adds value by noting scoped packages are accepted and version defaults to latest, which is not in the schema. Slightly below 5 because the additional info is minor.

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

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

The description clearly defines the tool as a composite check for npm package evaluation, covering license, advisories, bundle size, and more. It uniquely addresses 'is X safe/popular/small' queries, distinguishing it from sibling tools that serve other domains.

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 states use cases ('is X safe / popular / small' or 'what does adding lodash cost me') and delimits scope: NPM ecosystem only in v1, with fallback to deps.dev for other ecosystems. Provides clear when-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?

Beyond annotations (readOnly, idempotent, etc.), the description details embedding model, window size, character cap, and truncation behavior.

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

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

The description is front-loaded with main purpose, but it is a single dense paragraph. Some details could be streamlined without losing 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?

Covers purpose, when to use, pairing with sibling, technical details, and return value structure (passages with offsets and scores). No gaps given the constraints.

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%; the description largely repeats schema descriptions. No additional meaning is added beyond the schema for the parameters.

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 'search' and the resource 'inside a fetched record'. It distinguishes from siblings by mentioning its pairing with ask_pipeworx_grounded for a different workflow.

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 when the record is too big to cram into the prompt' and describes how it pairs with ask_pipeworx_grounded, providing clear usage context.

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

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

Discloses OAuth requirement, rate limits (10/day SMS), webhook auto-disable after 10 failures, and one-time secret. Annotations indicate idempotentHint=true, but description does not address whether duplicate subscriptions are allowed or how idempotency is enforced—minor gap.

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

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

Information-dense but well-structured: purpose first, then requirements, types, delivery details. Could be trimmed slightly (e.g., 'anonymous + BYO' phrase), but no wasted sentences.

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

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

Covers required parameters, optional delivery with constraints, type-specific params, and post-subscription behavior (feed always on). No output schema, but description states return value. Complete for a creation tool with nested objects and multiple types.

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%, yet description adds substantial value by explaining type-specific parameters (e.g., sec_8k items codes, polymarket_edge topics, fred series IDs) and details for delivery (webhook HMAC, phone verification). Exceeds 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?

Description clearly states action ('create') and object ('proactive monitoring subscription'), specifies return value ('new subscription id'), and covers supported types. Distinguishes from siblings like list_subscriptions and unsubscribe implicitly through action verb.

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 states requirement of Pipeworx OAuth account, lists supported types with parameters, and mentions delivery channels and limitations (SMS cap). Could be improved by explicitly contrasting with read-only tools (e.g., recent_alerts) or when to use alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by specifying the output format (category-bucketed example questions with tool+argument shape) and that it draws from a live catalog. 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?

Description is reasonably concise and front-loaded with alternative phrasings. Every sentence adds value, though slightly verbose with the list of categories. Good structure.

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

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

For a simple tool with one optional parameter and no output schema, the description is comprehensive: explains purpose, usage scenarios, output format, and relationship to other tools. 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% (topic parameter described). Description adds meaning by listing possible values and behavior when omitted ('Call with no arguments for the full spread'). Exceeds 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?

Description clearly states the tool is an onboarding entry point for a newly connected agent, lists alternative phrasings, and explains it returns category-bucketed example questions with exact tool and argument shapes. Distinguishes from siblings like ask_pipeworx by targeting users who don't know what to ask.

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 states 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on when to use the optional topic parameter. Lacks explicit when-not usage, but context 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?

Beyond annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), description adds that deactivation retains historical events and that ownership is enforced. 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, front-loaded with key action, no redundant information, efficient.

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

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

For a single-parameter tool with no output schema and well-covered annotations, the description provides all necessary context (ownership, idempotency, safety, impact on data).

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% coverage with parameter 'id' described as 'Subscription id (uuid) returned by subscribe.' Description does not add further semantic meaning beyond the schema, meeting 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?

Title 'Unsubscribe from Alerts' and description 'Cancel a subscription by id' clearly state the action and resource. Description adds ownership enforcement and deactivation behavior, distinguishing it from siblings 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?

Description explicitly states ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation vs deletion behavior, guiding when to use. Not explicit about when not to use but implies alternative for listing or subscribing.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, but the description adds substantial behavioral detail: the two pipeline paths, exact percent-delta math, verbatim evidence with pipeworx:// citation, and the nuanced distinction between 'could_not_verify' (check did not happen) and 'unsupported' (no source found). This goes far beyond the annotations and is essential for correct caller interpretation.

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

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

Although the description is lengthy, every sentence earns its place: trigger phrases, usage context, pipeline details, return values, and caller caveats are all included without redundancy. It is well-structured, front-loaded with purpose, and uses clear sections for different facets.

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

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

The tool is complex with two distinct paths and nuanced verdict semantics, but the description fully covers these aspects. It explains the return verdicts, error handling, citations, and comparative advantage over sequential calls, making it complete even without 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?

The input schema provides 100% coverage with clear descriptions for both 'claim' and 'tolerance_pct'. The description does not add any additional parameter semantics beyond what the schema already exposes, so a baseline score of 3 is appropriate.

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

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

The description uses specific action verbs ('validate', 'verify', 'fact check') and clearly defines the resource: natural-language factual claims verified against authoritative sources. It further distinguishes itself from siblings by noting it replaces 4–6 sequential calls (NL parsing → entity resolution → data lookup → comparison), making it a purpose-specific standalone 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?

Explicit usage guidance is provided: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also gives conditional routing (company-financial claims via SEC EDGAR/XBRL fast path, any other claim through grounded pipeline) and critical caller instructions on how to interpret 'could_not_verify' versus 'unsupported.'

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