Metabolights

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds context beyond annotations: it explains the default free model, that Anthropic requires a BYO key, and the return structure per model (score, confidence, signals, raw_response). 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?

Two concise paragraphs front-load the core purpose and output, then detail parameters and use cases. Every sentence adds value without redundancy or filler.

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

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

The description is complete for a tool with no output schema: it explains the per-model return fields and combined view, covers all parameters (required and optional), and gives clear usage context. No important gaps.

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

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

Schema coverage is 100%, but the description adds value by specifying the default model (Workers AI Llama-3.3-70b free), that _apiKey is passed through to Anthropic, and that context helps disambiguate entities. This enriches the schema descriptions.

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

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

The description explicitly states the verb (probe), resource (LLMs for business/brand/product/topic), and outputs a visibility score per model. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on scoring (0-100) and use cases like AI-marketing audits.

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 specific use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to provide optional parameters (context, _apiKey). However, it does not explicitly exclude itself from similar sibling tools or 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?

The description reveals internal behavior beyond annotations: it routes to '5,558 tools across 1461 verified sources', fills arguments, returns structured answers with 'pipeworx:// citation URIs', and notes it works on every tier with one fast call. This adds context not present in the readOnly/openWorld/idempotent hints.

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

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

The description is long but every sentence earns its place: usage priority, trigger examples, escalation rules, and internal details. It is front-loaded with the key 'PREFER OVER WEB SEARCH' directive and includes no filler or repetition.

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

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

Though there is no output schema, the description discloses the return format (structured answer with stable citation URIs), covers a wide range of use cases with domain examples, and clarifies when to escalate to alternatives. For a query-routing tool of this complexity, the description is remarkably 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 descriptions for all aliases, so the description need not explain parameters. It does provide examples of valid questions, but these only slightly complement the schema's own examples without adding deeper semantics like formatting or constraints. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: it answers factual questions about real-world data by routing to verified sources. It uses specific verbs ('PREFER OVER WEB SEARCH', 'Routes the question', 'returns the structured answer') and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research.

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

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

Guidelines are explicit: 'START HERE for most questions', with concrete escalation paths ('Step up only when needed' to ask_pipeworx_grounded or deep_research). It also lists trigger phrases like 'what is', 'look up', 'find' and includes multiple examples, making when-to-use unmistakable.

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, so the safety profile is covered. The description adds valuable context beyond annotations: it states the beta is a full working router, not a fallback, and reveals the current state (no active candidate) which affects behavior. This goes beyond what annotations alone provide.

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

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

The description is four sentences, each serving a distinct purpose: defining the beta nature, stating the current status, giving usage instructions, and clarifying that it is fully functional. There is no redundant wording or filler, and key information is front-loaded.

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

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

For a beta variant of an existing router, the description covers everything an agent needs: what it is, how it differs from the stable version, when to use it, and what to expect (same behavior currently). Mentions of 'same response shape' and 'full working router' address output and capability concerns. No output schema, but the description compensates sufficiently.

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

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

Schema coverage is 100% with all aliases documented in the input schema. The description only mentions 'same arguments' without adding any new meaning or constraints beyond what the schema already specifies, so it does not elevate the baseline.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,558 tools and response shape. It distinguishes itself from siblings like ask_pipeworx and ask_pipeworx_grounded by emphasizing the experimental routing improvements and its current equivalence to the stable router.

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: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. It also clarifies the current inactive-candidate state, so an agent knows when to choose this beta over the stable alternative.

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

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

Annotations already declare readOnly/openWorld/idempotent hints, but the description adds substantial behavioral context: it may return explicit refusals with distinct reasons (not_in_source, no_tool_match, etc.), uses only tool result content, and costs an extra LLM call. No contradictions with annotations.

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

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

The description is dense but each sentence earns its place: purpose, mechanism, output format, usage guidance, and cost trade-off. It front-loads the key concept and uses clear structure, making it easy to parse despite its length.

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

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

For a tool with no output schema, the description provides the full return structure and refusal semantics. It explains routing, extraction, and use cases, making it complete for an AI agent to decide and invoke correctly.

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

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

Schema coverage is 100% with all six parameters being aliases for the question. The description adds no extra parameter information, but the schema fully documents them. Baseline 3 is appropriate as the description doesn't need to compensate.

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: a hallucination-resistant answer mode for high-stakes reads. It uses specific verbs like 'EXTRACTS' and differentiates from the sibling ask_pipeworx by describing the same routing but with grounded extraction, plus explicit output format details.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and provides alternatives: 'prefer ask_pipeworx for casual lookups' and notes the extra cost. This gives clear context and exclusions.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds extensive behavioral context: low-confidence match short-circuiting, closed market handling, wide-spread market warnings, resolution-rule risk parsing, and fan-out patterns. 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 very long and detailed, with structured sections using bold headers. However, it could be slightly more concise; some details (like specific fan-out examples) are useful but add length. Front-loaded with 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?

No output schema, so description must fully explain response shapes. It covers resolver contract, parent event extractor, news fields, safety, wide-spread, resolution-rule risk, and more. Edge cases are explicitly addressed, making it highly 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%, but the description adds practical context: explains that 'market' accepts slug, URL, or text; that 'depth' defaults to 'thorough'; and that 'include_raw' false keeps responses small. This aids agent decision beyond schema alone.

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 researches a Polymarket bet by pulling Pipeworx data in one call. It provides multiple input formats and explicitly lists use cases, making the purpose unmistakable.

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

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

Explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It does not give explicit when-not-to-use instructions but implies scope through detailed examples and differentiation from sibling tools like ask_pipeworx.

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. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorted results, and citation URIs. 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 concise with 4 sentences, each adding unique value. It is front-loaded with example queries, making it immediately actionable. No redundancy or irrelevant information.

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

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

For a tool with no output schema, the description covers return format (paired data + citation URIs), data sources, sorting, and entity-specific behavior. It is complete enough for an AI agent to understand exactly what to expect.

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 enriches semantics by explaining what each type's data includes (revenue, net income, etc. for companies; adverse-event counts for drugs) and how results are sorted, going beyond the bare 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 uses specific verbs ('compare', 'side-by-side comparison') and resources ('companies or drugs'), includes example queries, and clearly distinguishes itself from sequential lookups, which are handled by sibling tools like 'entity_profile'.

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

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

Explicitly states 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Provides concrete context for when to use (comparison queries) and describes the behavior for each type. No explicit exclusions, but the guidance is strong.

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 annotations already cover readOnly/openWorld/idempotent, and the description adds substantial context beyond that: account tiers, parallel routing to 5,558 tools, latency, the findings packet structure (verbatim evidence, gaps[], contradictions[]), the citation_uri guarantee, and semantic excerpting. It also assures the agent that answers are never invented. This is far richer than the annotation baseline.

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

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

The description is extremely information-dense and front-loaded with the account requirement and key alternatives. However, it is a long wall of text with many parenthetical asides and em-dash clauses, which makes it harder to scan quickly than a bulleted or more structured format. Still, every sentence earns its place.

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

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

For a complex tool with only two parameters and no output schema, the description covers all essential context: preconditions, alternatives, when to use, latency, output structure, gap/contradiction behavior, and citation resolvability. Nothing material is missing for an agent to select and invoke the tool correctly.

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

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

Though the schema already describes both parameters (100% coverage), the description adds crucial semantics: depth is explained with concrete numeric facet counts ('quick=3', 'standard=5', 'thorough=8'), hop behavior, and paid tier implications. It also clarifies that question can be broad and multi-part, exceeding the schema's brief description.

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

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

The description uses a specific verb ('research') and a precise resource ('Pipeworx's 1461 STRUCTURED data sources'), and it explicitly distinguishes itself from both open-web search ('this is NOT open-web search') and sibling tools ('For a single lookup use ask_pipeworx'). This makes the tool's purpose unambiguous.

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

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

It gives explicit when-to-use guidance ('Best for broad/multi-part questions over structured data') and when-not-to-use guidance ('For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'). It also names the fallback tool for unsigned-in users. This is the gold standard for usage guidelines.

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 idempotentHint=true. The description adds that results include full schemas with curated examples and are 'ready to call directly, no second schema lookup needed.' This clarifies the return behavior 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 somewhat lengthy but front-loads the core purpose and provides a structured list of domains, then the return format, then usage advice. Every sentence adds value; no fluff.

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

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

Given the large sibling set and no output schema, the description adequately covers purpose, usage context, return details (top-N, full schemas), and gives a clear 'call this first' directive. Missing details like error handling are minor.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds examples and mentions aliases, but these are already implied by the schema. No critical meaning beyond schema is provided.

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

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

The description clearly states 'Find tools by describing the data or task' and enumerates numerous specific domains (SEC filings, FDA drugs, etc.), making the tool's purpose unambiguous and distinguishing it from siblings which are all specific tools.

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

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

Explicitly advises 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' Provides clear context for use but does not 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, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral context: it fans out across multiple sources, includes specific return fields, notes the USPTO patents soft-fail due to API sunset, and describes the GDELT→GNews fallback. 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 a single dense paragraph that is front-loaded with example queries, but it covers a lot of ground. While clear, it could be slightly more structured for easier parsing. Nonetheless, it is appropriately sized for the 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 has many siblings (30+) and no output schema, the description covers key aspects: inputs, sources, return fields, failure modes (patents), and alternatives. It omits pagination details, but annotations already indicate idempotent and read-only behavior. Overall, it is fairly 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%, but the description adds significant meaning: it explains that 'type' only supports 'company', that 'value' accepts ticker or zero-padded CIK but not names, and provides examples like 'AAPL' and '0000320193'. This beyond-schema detail helps the agent construct correct inputs.

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

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

The description clearly states the tool provides a full cross-source profile of a US public company in one parallel call, with examples like 'Tell me about X' and 'research Acme'. It distinguishes itself from chaining single-pack lookups and lists the data sources and returned fields, making the purpose very specific and actionable.

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

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

The description explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also specifies valid inputs (ticker or CIK) and directs users to 'resolve_entity' if they only have a name, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already cover destructiveHint=true and idempotentHint=true. Description adds usage context (stale, done, sensitive) beyond annotations, but no behavioral surprises.

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: first states action, second provides usage guidance. No wasted words.

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

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

For a simple tool with one required param and no output schema, the description fully covers what the tool does and when to use it.

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

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

One parameter 'key' with schema description 'Memory key to delete'. Description adds no extra meaning beyond schema. Schema coverage is 100%, so 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?

Clear verb+resource: 'Delete a previously stored memory by key'. Distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: context stale, task done, clear sensitive data. Also pairs with 'remember' and 'recall'.

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. The description adds context: fetches page, extracts title/description/key links, outputs markdown text blob ready for site-root/llms.txt. 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?

Two sentences plus a bullet list of use cases. No fluff, front-loaded with main action. Every sentence adds value.

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

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

Given no output schema, the description explains output format and deployment location. Could mention error handling or encoding but is sufficient for typical use.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds minor clarification on default and max for max_links but does not significantly increase 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 the tool generates an llms.txt file for AI crawlers by fetching a page and extracting content. It provides specific verb and resource, but does not differentiate from sibling tools like ai_visibility_check or 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 lists three concrete use cases: indexing a client's site, drafting llms.txt for own project, auditing competitor AI presence. However, it does not specify when not to use this tool or compare with related 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 already provide readOnlyHint and idempotentHint. Description adds behavioral detail like 'Keyless' (no authentication) and lists return fields, providing useful context beyond annotations.

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

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

Single sentence with no filler, clearly states purpose, input, and output.

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

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

Given no output schema, the description adequately lists what is returned (title, description, organisms). It could be more detailed but is sufficient 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% and includes example and description for 'id'. Description adds little beyond the schema, so 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?

Description clearly states the verb 'fetch' and the resource 'metadata for a single MetaboLights study'. It specifies the output includes title, full description, and organisms studied, distinguishing it from sibling tools like search_studies.

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 indicates usage requires a specific accession, but does not explicitly exclude other uses or mention alternatives like search_studies for broad queries.

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 this is a safe read operation (readOnlyHint=true, destructiveHint=false). The description adds transparency by listing return fields and mentioning the optional include_inactive parameter, but goes little beyond the annotations.

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

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

Two sentences, front-loaded, no redundant information. Every word adds value.

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

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

Given the simple tool (1 optional param, no output schema), the description fully covers what the agent needs: action, scope, return fields, and use cases. 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?

The schema has 100% description coverage for the single parameter (include_inactive). The description only implies its effect by stating 'active subscriptions.' Baseline 3 is appropriate since schema covers the parameter meaning.

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 (list), resource (subscriptions), and scope (caller's active). It also lists the return fields. While it doesn't explicitly differentiate from siblings like subscribe/unsubscribe, the purpose is 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 provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel.' This gives contextual guidance, though it does not discuss when not to use or alternatives.

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

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

Beyond the annotations (readOnlyHint=false, etc.), the description discloses key behaviors: filing returns a claim_token for later lookup, the token allows reading resolution status, rate limit of 5 per identifier per day, free usage, and that the team reads digests daily. This adds useful context without contradicting the annotations.

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

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

The description is long but every sentence carries essential information: use cases, exclusions, token mechanics, rate limits, and quota. It is front-loaded with the core action and then logically expands, with no redundant or filler 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?

Given the tool has no output schema and four parameters including a nested object, the description adequately covers what the agent needs: when to call, what to provide, how the claim_token follow-up works, and what to expect in return. It is self-contained for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra semantic value by advising not to paste the end-user's prompt, to describe issues in terms of Pipeworx tools/packs, and by explaining the claim_token round-trip pattern. This enriches parameter understanding beyond the schema.

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

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

The description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates exact use cases (bug, feature/data_gap, praise) and explicitly distinguishes itself from other MCP servers' tools, making it clear this feedback is only for Pipeworx-served tools.

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

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

Provides explicit when-to-use guidance (bug, feature, data_gap, praise) and equally explicit when-not-to-use guidance ('if the tool came from a different MCP server ... file it with that server instead'). Also includes a disambiguation hint ('Pipeworx tool names are the ones this connection lists') and a rate-limit note.

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, etc.), description adds that data is self-aggregating from CF analytics-engine, no PII, and cached 5min-1h, providing valuable behavioral context.

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

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

Concise and well-structured with bullet points. Every sentence adds value, though could be slightly more compact.

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

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

Given the simple tool (1 optional param, no output schema, rich annotations), the description fully covers purpose, usage, behavior, and parameter 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?

Schema coverage is 100% with enum. Description adds meaning by explaining shorter windows surface hot topics and longer windows show steady-state demand, exceeding baseline of 3.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a window, distinguishing it from siblings like discover_tools or ask_pipeworx by focusing on trending 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?

Identifies three specific use cases (discovering hot sources, confirming canonical choice, seeing alignment) but does not explicitly exclude 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, openWorldHint, idempotentHint. The description adds significant behavioral detail: Jaccard similarity filter (skipped_low_similarity), partition placeholder filter, and fill check against live CLOB depth. 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 appropriately structured with clear sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Despite length, 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?

Given the tool's complexity (multiple modes, filters, and response details), the description covers all necessary aspects. Even without an output schema, it explains the structure of the response including fields like gap_pp, suggested_trade, etc.

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

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

Input schema has 100% coverage with clear descriptions. The description adds further context: event parameter uses slug or full URL, topic parameter is a seed question; it also explains the behavior when no arguments are passed.

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 explicitly distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing on these specific methods.

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

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

The description provides explicit guidance on when to use each mode: no args for trending, event for specific markets, topic for cross-event scans. It also warns against trading when realizable_edge_pp ≤ 0 and directs to polymarket_fill_risk for custom sizing.

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

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

The description aligns perfectly with annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) and adds extensive behavioral context: caching at KV level keyed on knobs, exclusion of Fed bets from ranking with reasoning, and details on output structure including diagnostics for empty segments. 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 lengthy but well-structured with numbered model families, parenthetical explanations, and clear sectioning. It is front-loaded with the core purpose. However, some details (e.g., specific α values per sport, exact funnel counters) could be considered excessive for the tool description, though they add transparency.

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

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

The description fully explains the complex output structure (by_segment, fed_candidates, _diagnostics) and the rationale behind empty segments. Given that there is no output schema, the description carries the full burden and does so comprehensively, covering nine parameters with detailed guidance.

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 goes far beyond the schema by explaining the rationale behind defaults (e.g., slippage_pp: 'Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade'), providing boundary conditions (min_partition_leg_kelly: 'Partition arbs always return kelly_fraction_half=0 at the parent level'), and advising on when to adjust 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 starts with a clear verb-object pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It immediately distinguishes the tool from siblings like polymarket_arbitrage and polymarket_edge_tracker by specifying its unique methodology (Pipeworx data disagreement) and intended use case ('what should I bet on today').

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 its primary use case ('Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets') and provides detailed guidance on parameters like knobs for tradeability (min_liquidity, max_spread_pp). However, it does not explicitly state when to avoid this tool in favor of siblings, though the purpose is clear enough to infer.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds meaningful context: it reads from snapshots, depends on daily closes, returns time-series, and clarifies intraday vs. daily close nature. No contradictions with annotations.

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

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

The description is dense yet structured, with sections for args, response, and limits. It front-loads the core question. While verbose, every sentence contributes unique information, and the structure aids readability.

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 thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]) and their interpretations, covering edge cases like gaps. It addresses limitations adequately for a complex telemetry 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% and adequately describes both parameters. The description rephrases 'days' with slight variation (max vs. clamp) but adds no new semantic depth beyond informing defaults and constraints.

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

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

The description specifies the tool's purpose precisely: edge persistence and decay telemetry from daily snapshots. It answers a concrete question about edge age and trend. It distinguishes itself from raw snapshot data (e.g., polymarket_edges) by focusing on time-series and decay analysis.

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 strong usage context, explaining the interpretative value of edge age and decay. It includes limits (60-day TTL, daily close basis) but does not explicitly contrast with sibling tools or state when to avoid using 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 (readOnlyHint, idempotentHint, destructiveHint=false) already indicate the tool is safe and non-destructive. The description adds transparency by detailing what the tool returns (top_of_book, vwap_fill_price, slippage_pp, etc.) and the risks (e.g., forced directional risk in basket mode). No contradictions with annotations.

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

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

The description is long but well-structured with clear sections for single-market and basket modes. Every sentence conveys important information, and the use of bold for key terms helps readability. Slightly verbose but appropriate given the 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 no output schema, the description thoroughly enumerates all return fields (e.g., top_of_book, vwap_fill_price, slippage_pp, verdict) for both modes. It explains edge cases (thin legs, forced directional risk) and covers default values. The description is complete enough for an agent to understand what the tool provides.

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

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

Input schema has 100% description coverage, so the schema already documents each parameter. However, the description adds value by explaining how parameters behave differently in single-market vs basket mode (e.g., size_usd interpretation) and default behaviors. This goes beyond the schema's static 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's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between two modes (single-market and basket) and explains each, making it easy for an agent to understand what the tool does. This differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly directs when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains the risks of partial fills and that theoretical overround on thin books is not capturable, providing clear guidance on usage.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive behavior. Description adds depth: explains safety fields, skipped counters, temporal alignment, and compatibility conditions, with no contradictions.

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

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

Description is somewhat lengthy but well-structured with sections (MODES, RESPONSE, SAFETY FIELDS). Every sentence adds information, though slight redundancy exists (e.g., repeated mention of compatibility warning). Could be slightly more concise without losing clarity.

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 thoroughly explains response structure (venue legs, matched spread, safety fields) and provides rich context about when spreads are meaningful. Completely adequate for an agent to select and invoke correctly.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). Description adds value by listing valid topic values and explaining how explicit parameters override the topic mode, but schema already handles parameter meaning 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools by focusing on these specific venues and the spread concept.

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 describes two modes (topic shortcuts or explicit tickers) and provides detailed guidance on when spreads are meaningful, including compatibility warnings and temporal alignment checks.

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, destructiveHint. Description adds context about scoping by identifier and behavior when key is omitted, adding value 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?

Every sentence adds value; front-loaded with main action. Concise yet informative.

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

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

Complete for a simple tool with one parameter and good annotations. Slightly more detail on return format could improve, but not necessary.

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 already explains the parameter behavior. Description adds no new information beyond schema, meeting baseline but not exceeding.

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 action (retrieve/list) and resource (saved keys/values), and distinguishes 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?

Provides explicit examples of when to use (look up stored context) and mentions pairing with remember/forget, but does not explicitly state when not to use.

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

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

The description states that setting mark_read:true flags events as read, modifying state for future calls. This contradicts the annotation readOnlyHint:true, which claims the tool is read-only. The inconsistency could mislead agents.

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?

Five sentences, no fluff. The core purpose is front-loaded, followed by return details, filtering, mark_read behavior, and alternative access. Every sentence adds value.

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

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

Covers return fields, filtering, mark_read behavior, and alternative access. Lacks pagination details but schema provides it. Sufficient for a read tool with annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for type ('sec_8k') and explains mark_read's effect, but adds limited value beyond the existing schema descriptions.

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

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

The description clearly states 'Pull fired events from your subscription feed' with a specific verb and resource. It lists returned fields (source, citation_uri, payload) and filtering options, distinguishing it from siblings like 'recent_changes' or 'subscribe' by focusing on alert events.

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

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

It explains when to use the tool (polling alerts) and provides an alternative HTTP endpoint for scripts/dashboards. However, it does not explicitly contrast with sibling tools like 'list_subscriptions' or 'subscribe'.

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, idempotentHint, and nondestructive. Description adds significant behavioral context: fans out to multiple sources, has fallback logic, and notes that USPTO may soft-fail. Also describes return structure (changes[] grouped by source, total_changes, citation URIs). 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 somewhat long but every sentence adds value. It is well-structured: begins with example queries, then describes backend fan-out, parameter guidance, and alternative tool. Front-loaded with purpose. Minor redundancy could be trimmed but overall efficient.

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

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

Given the tool's complexity (multiple data sources, fallback, soft-fail, no output schema), the description is thorough. It explains what the tool does, how it operates, parameter semantics, and return format. Combined with annotations (readOnlyHint, etc.), the agent has adequate context to use it correctly.

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

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

Schema coverage is 100%, but description enriches each parameter: for 'since' it explains ISO date vs relative shorthand and suggests '30d' or '1m'; for 'value' it clarifies ticker or CIK formats; for 'type' it states only 'company' is supported. Provides concrete examples like 'AAPL' and '0000320193'.

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 starts with clear example queries ('What's new with X', 'latest on Y') and states the tool's purpose: 'change feed for a company in the last N days/weeks/months in ONE parallel call'. It also distinguishes from sibling tool entity_profile by specifying when to use the alternative.

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 tells when to use this tool over alternatives: 'Use entity_profile instead when you want the static profile'. Provides guidance on parameter values (e.g., 'Use "30d" or "1m" for typical monitoring') and explains fallback behavior (GDELT→GNews) and limitations (USPTO soft-fail).

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

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

Description adds scoping by identifier and persistence differences (authenticated vs anonymous) beyond annotations, which already indicate idempotent and non-destructive 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?

Three well-structured sentences: purpose, usage context, technical details. No redundant information; every sentence is essential.

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

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

For a simple two-param tool with no output schema, the description covers purpose, when to use, technical details, and pairing with sibling tools. Complete and self-contained.

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

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

Schema has 100% description coverage, but description provides helpful examples (subject_property, target_ticker) and clarifies key purpose and value content, adding meaning beyond schema.

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

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

The description clearly states the tool saves data for reuse, specifies the verb 'save' and resource 'data', and distinguishes from siblings recall and forget with concrete examples.

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

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

Explicitly says when to use ('when you discover something worth carrying forward'), provides context (across conversations/sessions), and pairs with recall/forget for complete workflow.

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

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

The description adds substantial behavioral context beyond annotations: it explains the cross-source identity spine, labeling of identifiers with sources, explicit handling of unresolved identifiers, graceful degradation when external services are unavailable, and internal cascading through multiple endpoints. This is rich, non-redundant detail that annotations do not provide.

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

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

The description is dense and somewhat long, but each sentence earns its place by adding essential detail on purpose, supported types, fallback behavior, and return characteristics. It is well-structured with a clear flow, though slightly verbose, preventing a perfect score.

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

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

Without an output schema, the description fully explains what the tool returns: canonical identifiers with source labels, unresolved identifiers explicitly listed, and enriched ownership/security data. It covers input variations, degradation behavior, and internal cascading, making it complete for a tool of this complexity.

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

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

Even though schema coverage is 100%, the description significantly enhances parameter meaning. It explains accepted input formats for 'value' (ticker, CIK, ISIN, or name for company; brand/generic for drug), gives concrete examples, and describes special cases like ISIN-to-LEI mapping. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific verbs like 'resolve' and a clear resource scope. It distinguishes itself from siblings by positioning it as the first step for other tools and by listing supported entity types (company, drug) with examples.

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 instructs 'Use FIRST whenever you have a name but need an ID', providing a clear when-to-use directive. It also implies when-not-to-use (if you already have an ID) and gives context on how it replaces multiple manual lookups, effectively differentiating from 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds that it internally calls ai_visibility_check, ranks by score, and returns specific fields (score, confidence, signal density), providing behavioral details beyond annotations.

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

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

Three sentences with no wasted words: first sentence states core function, second explains internal process, third gives use case and output format. Front-loaded with essential info.

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

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

With 4 parameters, no output schema, the description covers return fields (score, confidence, signal density) and entity count range (2-8). It does not detail output structure or pagination, but for a ranking tool, this is sufficient.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining that the first entity is the subject, models can be omitted for free default, and context disambiguates. This exceeds minimal schema info.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each entity with ai_visibility_check, and ranks results. This distinguishes it from siblings like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

The description notes it is useful for competitive AI-marketing audits, implying when to use. However, it does not explicitly state when not to use or directly name alternatives, though siblings provide context.

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds significant behavioral context: it fans out to two external services, returns a specific block of data, and degrades gracefully on partial failures with sources_failed field. It also warns about bundlephobia's slow initial measurement. 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 a single paragraph that is front-loaded with the core purpose. Every sentence adds value, including usage guidelines, limitations, and return details. There is no wasted text; it is concise yet comprehensive.

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

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

Given the absence of an output schema, the description fully covers the return structure: a summary block with fields (is_latest, license, etc.), per-advisory details, links, and recent alternative versions. It also explains partial failure handling. This provides sufficient context for an agent to understand what to expect.

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: it confirms scoped packages (e.g. '@types/node') are accepted for the 'package' parameter, and clarifies that 'version' defaults to the latest published version when omitted. This provides useful semantic guidance for the agent.

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: a composite check for deciding whether to add an npm package, combining data from deps.dev and bundlephobia. It uses a specific verb ('scan') and resource ('dependency') and distinguishes itself from any sibling tools by specifying the npm ecosystem and the combined sources.

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 when to use: for questions like 'is X safe/popular/small' or 'what does adding lodash cost me'. It also notes limitations: NPM only in v1, with alternatives for other ecosystems (PyPI, Maven, etc.) mentioned. Additionally, it explains partial failure behavior and timing expectations (5-30s for bundlephobia first measurement).

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by naming the specific repository (EBI MetaboLights) and clarifying the result includes accessions, name, and short description. 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?

Single paragraph front-loaded with action verb 'Search'. Every sentence provides key information: what it searches, how to search (examples), what it returns. 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?

No output schema, but description compensates by stating return format (accessions, name, short description). Parameter coverage perfect. Annotations handle safety/idempotency. Adequately complete for a search tool with two parameters.

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

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

Schema covers 100% of parameters with descriptions. The description adds examples (e.g., 'diabetes', 'glucose NMR') and explains that query can include disease, metabolite, organism, or technique, enriching beyond schema's free-text description.

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

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

The description clearly identifies the tool as searching the EBI MetaboLights repository by keyword, specifying resource type (metabolomics studies) and result format (accessions, name, description). It distinguishes from sibling 'get_study' by implying a list vs. single study retrieval.

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 keyword examples and scope (disease, metabolite, organism, technique). While no direct 'when-not-to-use' is stated, the examples and reference to 'matching studies' imply search context, and sibling names like 'get_study' suggest alternatives for individual studies.

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 embedding model, window size, character limit with truncation flag, and return fields (offsets, scores). Adds value beyond annotations which only state readOnly, idempotent, not 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, front-loaded with main purpose, each sentence adds critical info without fluff. Highly efficient.

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

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

Despite no output schema, description fully explains return values (offsets, scores) and input constraints (200K chars, truncation). Pairs well with sibling and covers all agent needs.

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 real-world examples (e.g., 'supply-chain risk'), default value for limit, and context that text is 'already pulled'. Enhances 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?

Clearly states 'semantic search INSIDE a fetched record' with verb and resource, and distinguishes from siblings like ask_pipeworx_grounded. Specific use case given.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt'. Also suggests pairing with ask_pipeworx_grounded and explains benefits.

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 mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds details about the webhook secret being returned once, phone verification, rate limits (10/day), and auto-disabling after 10 failures. This goes well 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 comprehensive but somewhat verbose. It is front-loaded with the main action and uses examples effectively. Minor redundancy could be trimmed, but overall it earns its length.

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

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

Despite no output schema, the description explains what is returned (subscription ID, webhook secret). It covers all types, parameters, delivery options, prerequisites, and limitations, making it sufficient for an agent to use correctly.

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

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

Schema coverage is 100%, but the description adds significant value by providing concrete examples for each type (e.g., 'sec_8k' with items codes, 'polymarket_edge' with topics) and clarifying delivery channel usage. It enriches understanding beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns a subscription ID. It distinguishes itself from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 specifies a prerequisite (Pipeworx OAuth account) and provides examples for each subscription type. While it doesn't explicitly state when not to use it, the context of creating new subscriptions is clear. It could mention alternatives like 'recent_alerts' for pulling existing alerts.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description does not need to repeat these. It adds context about returning example questions and tool shapes but does not disclose any significant behavioral traits beyond what annotations provide.

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

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

The description is a single paragraph of moderate length, but it is front-loaded with common user queries and each sentence adds meaningful information. It efficiently covers purpose, usage, parameters, and output 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 optional parameter and no output schema, the description fully explains the return value (category-bucketed example questions with tool shapes) and the effect of the topic parameter. It is sufficient for an agent to understand and invoke the tool correctly.

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

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

Schema coverage is 100%, as the only parameter (topic) is described with potential values in the schema. The description adds value by listing example focus areas and explaining that omitting topic yields a cross-category spread, enriching the semantic meaning beyond the schema's description.

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

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

The description clearly identifies the tool as an onboarding entry point that returns category-bucketed example questions with tool+argument shapes. It uses specific verbs ('suggest questions', 'return', 'focus') and distinguishes itself from sibling tools by being the first tool to call when learning about Pipeworx's capabilities.

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

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

Explicitly 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', providing clear context for when to use. It also explains how to narrow focus with the topic parameter, though it does not explicitly mention 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 provide non-readOnly, non-destructive, and idempotent hints. The description adds that the row is deactivated (not deleted) and that historical events remain accessible via recent_alerts. This explains the non-destructive nature and consequence. 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?

Two sentences that are concise and front-loaded. The first sentence states the primary action and constraint, the second explains the effect. 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?

For a simple tool with one parameter, no output schema, and annotations covering safety, the description is fairly complete. It covers purpose, constraint (ownership), and effect (deactivation). Could be improved by explicitly mentioning idempotency or error conditions, but overall sufficient.

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

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

Schema coverage is 100% and the schema already describes the id parameter in sufficient detail ('Subscription id (uuid) returned by subscribe'). The description does not add any additional parameter information, so the 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 'Cancel a subscription by id.' It uses a specific verb (cancel) and resource (subscription). It also adds ownership enforcement and the effect of deactivation, distinguishing it from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly says 'Ownership is enforced — you can only cancel your own subscriptions,' which tells the agent when to use it (for own subscriptions) and implies not for others'. It also mentions that historical events stay available via recent_alerts, providing context. However, it does not explicitly state when not to use it or mention alternatives.

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

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

Beyond the read-only, open-world, and idempotent annotations, the description reveals the dual verification paths (structured SEC EDGAR fast path vs. grounded pipeline), the specific verdict types, and the critical nuance that 'could_not_verify' means the check did not happen and must not be treated as evidence. It also discloses citation and reasoning outputs, providing substantial behavioral context.

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

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

The description is relatively long but well-structured, front-loading example phrasings and a clear purpose statement before diving into implementation details. Every section adds value, including the important caveat about 'could_not_verify'. It could be tightened slightly, but it earns a strong score.

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 values: verdict types, actual values with citations, and reasoning. It also covers pipeline routing, call efficiency, and error semantics. Given the tool's complexity and lack of structured output, the description is remarkably complete and covers edge cases like 'unsupported' and 'could_not_verify'.

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

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

The input schema already provides full descriptions for both parameters (claim and tolerance_pct) with 100% coverage, so the baseline is 3. The description adds only marginal parameter-related context (e.g., 'exact percent-delta math') without elaborating on parameter syntax or behavior, so it does not lift the score 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?

The description clearly identifies the tool as a natural-language claim verification service, with explicit use-case phrases like 'fact check' and 'verify the claim that…'. It specifies the resource (authoritative sources) and differentiates between financial claims via SEC EDGAR/XBRL and all other claims via a grounded pipeline, making its purpose unmistakable and distinct from sibling tools.

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

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

The description gives explicit when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes that it replaces 4–6 sequential calls, implying an alternative manual approach. However, it does not explicitly name sibling tools or state when not to use it, so it falls short of full 5.

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