Schemastore

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive nature. Description adds that Anthropic calls require a BYO key and direct payment, and returns per-model details. No contradictions; description complements annotations well.

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

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

Concise, front-loaded description in a few sentences. No unnecessary details; each sentence serves a purpose (what, defaults, returns, use cases). Well-structured.

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

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

Despite lacking an output schema, the description succinctly details the return structure (per-model fields + combined view). Covers all parameters with examples and explains optional behavior. Complete for a moderate-complexity tool.

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

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

Schema description coverage is 100% (all 4 parameters documented). Description adds value by explaining the default model, how `_apiKey` relates to Anthropic, and the purpose of `context`. Exceeds the baseline of 3 for high-coverage schemas.

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 uses specific verbs ('probe', 'score visibility') and clearly states the resource (LLMs for business/brand/product/topic). It distinguishes from siblings by focusing on AI visibility scoring per model, contrasting with related tools like 'scan_competitor_ai_presence'.

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

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

Explicitly lists use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide `_apiKey` for Anthropic. Lacks explicit when-not-to-use or direct comparisons to siblings, but the context is clear.

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

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

Annotations already signal read-only, open-world, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that: the tool routes to a huge tool ecosystem, fills arguments automatically, and returns structured answers with stable pipeworx:// citation URIs. It does not discuss failure modes or latency, but the existing annotations lower the burden here.

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 front-loaded with the key 'PREFER OVER WEB SEARCH' message. The domain list, trigger phrases, and examples all earn their place for a broad routing tool. Minor redundancy exists between 'PREFER OVER WEB SEARCH' and 'even if web search could also answer it,' but overall the structure is effective.

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

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

The description covers the tool's purpose, when to use it, how it behaves internally, and what it returns, which is especially valuable since there is no output schema. It is complete enough for an agent to invoke the tool with a raw natural-language question. It could be more complete by naming specific sibling tools to prefer or avoid, but this is a modest gap.

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%, with every parameter described as an alias for 'question.' The description provides examples but adds no parameter semantics beyond what the schema already states. This is the appropriate baseline for fully documented parameters.

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

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

The description clearly states the tool's function: it 'routes the question to the right one of 5,798 tools across 1517 verified sources, fills arguments, returns the structured answer with stable pipeworx:// citation URIs.' This is a specific verb+resource description that goes well beyond the name. However, it does not differentiate from similarly named siblings like ask_pipeworx_beta or ask_pipeworx_grounded, so it misses the top score.

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: prefer over web search for factual/real-world questions, lists trigger phrases, gives domains, and provides concrete examples. It also includes the exclusion 'except when a more specific tool fits.' However, it does not name those more specific alternatives, so an agent must infer which sibling tools should take precedence.

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 established. The description adds valuable context beyond that: the experimental candidate-testing behavior, the temporal state (last candidate retired 2026-07-26), results being compared against the stable router, and the explicit 'falls back to nothing — this IS a full working router' guarantee that preempts a likely misconception.

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

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

Four sentences, each earning its place: identity and scope, current experimental state, usage guidance with alternative, and fallback clarification. The beta distinction is front-loaded. Slightly dense, but nothing is redundant and the temporary-state disclosure is essential rather than filler.

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

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

For a high-complexity tool (router over 5,798 tools) with no output schema, the description covers identity, current operational state, when to use it, and the no-fallback guarantee, while pointing to ask_pipeworx for response shape. It is complete enough because it deliberately defers details to a known sibling; a concrete example of routing behavior would be the only meaningful addition.

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%, with all six parameters documented as aliases for the single required 'question' parameter. The description references 'same arguments' as ask_pipeworx, which is a useful cross-reference, but it adds no parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: it is a universal router over 5,798 tools, explicitly identified as the beta variant of ask_pipeworx. It differentiates itself from its sibling by naming the candidate-routing improvement mechanism, so an agent can distinguish it from ask_pipeworx and ask_pipeworx_grounded without opening schemas.

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

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

Explicitly says when to use it ('when you want the newest routing'), names the stable alternative (ask_pipeworx), and clarifies the current state of behavioral equivalence because no candidate is active. It does not enumerate exclusions or other alternatives like ask_pipeworx_grounded, but the primary routing decision is well covered.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description goes well beyond this by revealing the exact success response shape, the explicit refusal reasons, the extraction-only-from-source behavior, and the added cost of one LLM call. No contradictions exist.

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

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

The description is dense but every major section earns its place: purpose, behavior, return format, refusal reasons, usage guidance, and cost tradeoff. It is front-loaded with the core promise. Slightly long due to the exhaustive refusal list, but that list is directly actionable for agent decision-making.

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

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

Given there is no output schema, the description compensates thoroughly by specifying return fields, refusal semantics, success conditions, failure modes, and the tradeoff versus the sibling tool. Schema covers parameters; description covers behavior and output. Nothing essential for a grounded answer tool is missing.

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

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

The input schema covers 100% of parameters, including all aliases for question, so the schema already carries the semantic load. The description does not add parameter-level detail beyond noting the routing and argument-filling behavior, which is sufficient but not augmentative. This matches the baseline for complete schema coverage.

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

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

The description clearly identifies a specific behavior: a grounded, hallucination-resistant answer mode that extracts answers only from tool results, and explicitly contrasts itself with ask_pipeworx. It names the resource (the pipeworx tool ecosystem) and the special guarantee, making it easy to distinguish from siblings.

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

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

The description gives explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists example domains. It also provides a clear when-not-to-use: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost. This fully equips an agent to choose appropriately.

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

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

Annotations already indicate safe, idempotent, read-only behavior. The description goes beyond with details on low-confidence short-circuit, closed market handling, wide spread warnings, resolution-rule risk, and cancellation rules—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 long but well-organized with sections and examples. It front-loads the purpose and is structured, though slightly verbose for the amount of detail.

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

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

Given the complexity (3 parameters, no output schema), the description covers all essential aspects: input resolution, classification, fan-out, response shapes, edge cases, safety, and cancellation rules. It is fully 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 covers 100% of parameters with descriptions. The description adds meaning: market can be slug, URL, or question; depth has quick/thorough with default; include_raw explains usage. Examples further clarify.

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

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

Description clearly states the tool researches Polymarket bets by pulling Pipeworx data, resolving markets, classifying bets, and returning evidence packets. It gives specific inputs (slug, URL, question) and examples, distinguishing it from sibling tools like 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?

Explicitly states use cases (e.g., 'should I bet on X', 'what does the data say about Y') and provides extensive examples and edge-case handling (low confidence, closed markets). However, it 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds specifics: pulls latest 10-K data from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, and uses FAERS/FDA data for drugs. This complements annotations without contradiction.

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

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

The description is relatively long but well-structured. It front-loads the purpose with common query patterns, then details data retrieval specifics. Every sentence provides essential information, though a slightly more concise phrasing could improve 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?

Given no output schema, the description explains the return format (paired data + citation URIs, sorted by primary metric). It covers both entity types comprehensively, including data sources and handling of fiscal years. For a tool with two parameters, this is thorough.

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

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

Input schema has 100% coverage with descriptions. The description adds semantic value by explaining the data sources for each entity type and the expected format (tickers/CIKs for company, drug names for drug). It also clarifies the min/max items and sorting behavior.

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

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

The description uses specific verbs like 'compare', 'side-by-side', and lists example queries ('X vs Y', 'which is bigger'). It clearly distinguishes from sequential lookups and entity profiles by stating it replaces '8–15 sequential lookups'.

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

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

The description explicitly states 'ALWAYS PREFER over sequential single-pack lookups' and provides example contexts ('rank these companies', 'head to head'). It lacks explicit 'when not to use' but the context is sufficient.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses account and paid-tier requirements, the fact that findings never invent gaps, the fetchability guarantee for citation_uri, contradiction behavior for standard/thorough, and latency expectations. These operational details go well beyond what annotations convey.

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

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

The description is front-loaded and information-dense, with nearly every sentence adding real value. However, it contains a stray editorial artifact 'Wait, no:' that should not be there, and the overall length is high. This prevents it from being a top conciseness 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 present, the description correctly compensates by explaining the findings packet: verbatim evidence, confidence, source, fetched_at, gaps[], contradictions[], hop field, and citation_uri. It also covers auth prerequisites, tier restrictions, alternatives, and runtime expectations, so an agent has the full picture needed to call the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds depth-specific context such as latency expectations ('Expect 15-60s; thorough up to ~90s') and clarifies behavior of standard/thorough around gap recovery and contradictions. The question parameter itself gains little beyond the schema, but the extra depth context is genuinely useful.

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

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

The description states a clear verb+resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources' and explicitly says 'this is NOT open-web search.' It also distinguishes itself from siblings by naming ask_pipeworx for single lookups and providing concrete examples of broad/multi-part questions.

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

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

It explicitly gives conditions for when not to use the tool: 'If you are not signed in, use ask_pipeworx instead' and 'For a single lookup use ask_pipeworx instead.' It also states the intended use case: 'Best for broad/multi-part questions over structured data.' This is strong, actionable routing guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering safety. The description adds beyond: it returns top-N relevant tools with names, descriptions, and full input schemas, and states each result is ready to call directly, eliminating the need for a second schema lookup.

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 front-loads the main purpose, then lists domains, explains output, and gives usage guidance. Every sentence adds value with no redundancy or fluff.

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

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

Given no output schema, the description compensates by detailing the return format: top-N tools with names, descriptions, and full input schemas. It covers the key aspects for an agent to understand and invoke the tool, though it omits details like scoring or pagination.

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% with aliases and descriptions. The description adds context by explaining that the query should be a natural language description and provides examples (e.g., 'analyze housing market trends', 'look up FDA drug approvals'), which enhances 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's purpose: 'Find tools by describing the data or task.' It uses a specific verb+resource pattern, lists domains like SEC filings, financials, etc., and distinguishes itself from sibling tools by focusing on discovering other tools rather than directly answering queries.

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

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

The description explicitly guides when to use: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It also contextualizes usage for browsing, searching, looking up, or discovering tools, contrasting with tools that provide direct answers.

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 readOnly, idempotent, and non-destructive hints, so the bar is lower, but the description adds substantial behavioral context. It details the fan-out across sources, the exact fields returned, the USPTO patent soft-fail due to the API sunset, the GDELT→GNews fallback, the meaning of sources_used/sources_failed, and the private-company resolved:false behavior with explicit notes. This goes well beyond the annotations.

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

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

The description is long but information-dense; each sentence adds a meaningful detail about sources, return fields, or edge cases. It is front-loaded with query examples and the key 'prefer over chaining' directive. Some slight redundancy exists with the schema (e.g., type/value shape), but overall the length is justified by the tool's complexity.

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

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

There is no output schema, so the description must explain return values itself—and it does. It enumerates all result sections (cik, recent_filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI), explains the meanings of fields like sources_used/sources_failed, and covers failure modes such as private companies and the patent API sunset. An agent has everything needed to invoke and interpret 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 description coverage is 100%, so the baseline is 3. The description reinforces that 'type' accepts 'company' or 'ticker' interchangeably and that 'value' can be a ticker, CIK, or name, but this is already fully stated in the input schema. The description adds examples like 'AAPL' and '0000320193', which are helpful but not semantically necessary.

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

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

The description states a specific verb and resource: it produces a 'full cross-source profile of a US public company in ONE parallel call.' It clearly distinguishes this from chaining single-pack SEC/XBRL/news lookups by saying those should be avoided in favor of this tool for holistic views. The included query examples ('Tell me about X', 'research Acme', 'brief me on Tesla') make the intended use 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 explicitly says to prefer this tool over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view, and gives concrete example queries that trigger it. It also explains behavior for private companies and notes that an empty section is a real 'no data.' However, it does not directly name or distinguish sibling tools like compare_entities, deep_research, lookup, or resolve_entity, so the guidance is strong but not fully exhaustive.

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 the important behavioral constraint about the allowed URL domain, which is beyond what annotations provide. No contradiction.

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

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

Single, front-loaded sentence with no wasted words. Every part is essential for understanding the tool.

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

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

Given the presence of an output schema and annotations, the description is complete. It covers the key constraint and purpose without omission.

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

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

Schema coverage is 100% with examples. The description adds minimal value beyond the schema, simply restating that the URL is a fetch target. 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 action ('Fetch') and resource ('JSON Schema document') with a specific constraint ('must be hosted on json.schemastore.org'). This distinguishes it from sibling tools like 'find_schema_for' and 'list_schemas'.

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

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

The description provides a clear when-to-use constraint (URL must be on json.schemastore.org) but does not explicitly mention alternatives or when not to use this tool. However, the constraint itself guides the agent.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds the matching logic and what is returned (schema name, description, fileMatch globs, URL), which is useful context beyond the annotations.

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

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

The description is three sentences, each earning its place: purpose, examples, return payload, and use case. No fluff or repetition.

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

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

Given the simple one-parameter tool, presence of an output schema, and comprehensive annotations, the description fully covers the tool's function, return values, and use case. No missing critical information.

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

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

The schema fully describes the filename parameter (100% coverage), so the baseline is 3. The description reinforces with examples like package.json and .github/workflows/ci.yml, adding clarity about what constitutes a config filename.

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

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

The description states a specific action: 'Match a config filename against the SchemaStore catalog...' and explains it returns matching catalog entries. It clearly distinguishes from sibling tools like fetch_schema by focusing on identifying which JSON Schema validates a given config file.

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

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

The description gives clear context: use when you need to determine which JSON Schema validates a config file, with the explicit purpose of pointing an editor or linter. It does not explicitly name alternatives or state when not to use it, but the use case is well-defined.

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 aligns with annotations (destructiveHint=true) by stating 'delete' and 'clear'. Adds behavioral context about data sensitivity and staleness 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?

Two sentences: first states purpose, second provides usage guidance. Front-loaded and 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 destructive tool with one parameter and no output schema, the description covers purpose, usage, and pairing. Annotations provide destructive hint. Reasonably complete.

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

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

Schema description coverage is 100% for the single 'key' parameter with description 'Memory key to delete'. Description does not add parameter-specific details beyond schema, 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?

The description states 'Delete a previously stored memory by key' which is a specific verb and resource. It distinguishes from related tools 'remember' and 'recall' by mentioning them, but does not fully differentiate when to use each.

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: 'when context is stale, the task is done, or you want to clear sensitive data'. Mentions paired tools 'remember' and 'recall', but lacks explicit when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it fetches the page and extracts content, but does not elaborate on external requests or rate limits. This adds marginal 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?

The description is a single paragraph that efficiently covers purpose, input, output, and use cases. It is concise without being too terse, though a list for use cases could improve 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?

Given the simplicity of the tool (2 parameters, no output schema), the description fully covers what the tool does, how it works, and what it produces. No additional information is necessary for correct usage.

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

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

With 100% schema coverage, the description still adds value by stating the default for max_links (25) and its max (50), which is not in the schema's description field. The url parameter is straightforward.

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 a llms.txt file for a URL, specifying the verb 'generate' and resource 'llms.txt file'. It distinguishes from sibling tools like ai_visibility_check and scan_competitor_ai_presence by focusing on file generation rather than 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 explicit use cases: getting a client's site indexed, drafting for own project, auditing competitors. It does not mention when not to use or alternatives, but the context is clear enough for typical scenarios.

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 the tool is read-only, non-destructive, idempotent, and open-ended. The description adds that filtering is case-insensitive and applies to name, description, and fileMatch. This provides additional behavioral context beyond the annotations.

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

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

The description is a single sentence of 16 words, efficiently conveying the essential behavior. It is front-loaded with the main action and includes the key detail about filtering. No unnecessary verbiage.

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

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

Given the presence of an output schema and comprehensive annotations, the description adequately covers the tool's functionality. It explains the filtering capability but does not mention pagination or limit behavior beyond what is in the schema.

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

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

The input schema describes both parameters with basic examples. The description clarifies that the filter is case-insensitive and applies to specific fields (name, description, fileMatch), which adds meaning beyond the schema's simple examples.

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

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

The description clearly states the tool lists SchemaStore catalog entries and mentions the optional filter. The purpose is specific, but it does not explicitly differentiate from sibling tools like 'fetch_schema' or 'find_schema_for', which are also schema-related.

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

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

No guidance is provided on when to use this tool versus alternatives. For example, if a user needs a specific schema, they might prefer 'fetch_schema' or 'find_schema_for' instead. The description only mentions the filter capability without explaining when it is appropriate.

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

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

Annotations already indicate read-only, idempotent, non-destructive. Description adds return fields and parameter behavior (include_inactive). 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 with no waste. Purpose front-loaded, followed by usage guidance. Efficient and well-structured.

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

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

Given annotations and schema, the description is sufficient. Provides purpose, usage, return fields, and parameter hint. No output schema needed as return fields are listed.

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

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

Schema coverage is 100% for the single parameter `include_inactive`. Description does not add extra meaning beyond the schema, so baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with verb and resource. Lists return fields, distinguishing from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

Provides explicit context: 'review what you're monitoring before adding more or to find an id to cancel.' Does not explicitly state when not to use, but context is clear.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint). The description adds valuable behavioral detail: 'exact-name' and 'case-insensitive', which go beyond annotations. However, it does not mention what happens if the name is not found or any limits, but this is partially mitigated by the output schema.

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

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

The description is a single, front-loaded sentence with no extraneous content. Every word adds value, making it highly concise and structurally effective.

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

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

For a simple one-parameter tool with rich annotations and an output schema, the description covers the essential behavior. It could clarify what 'the catalog' contains (e.g., schemas, entities) but is still largely sufficient for an agent.

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

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

Schema coverage is 100%, with the 'name' parameter described via an example. The description adds no new parameter details, but given high coverage, the baseline of 3 is appropriate.

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

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

The description states 'Exact-name lookup against the catalog (case-insensitive),' clearly identifying the action and resource with specificity. However, it does not explicitly differentiate from sibling tools like 'find_schema_for' or 'search_within', which could reduce clarity in selection.

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 no guidance on when to use this tool versus alternatives such as 'search_within' or 'find_schema_for'. It implicitly suggests using it when the exact name is known, but lacks explicit when-not-to-use instructions or recommended 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?

All annotations are false, so the description carries the full burden. It discloses the claim_token return mechanism, rate limits, daily digest review, no quota impact, and the ability to later query status with the token. These are meaningful behavioral traits beyond what annotations could convey, with no contradictions.

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

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

The description is longer than average (about 9 sentences), but every sentence contributes distinct information: purpose, when to use, exclusions, token flow, digests, rate limits, and cost. It is well-structured and front-loaded, though slightly verbose; a tighter wording could achieve the same 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?

For a tool with no output schema but a nested parameter object, the description fully covers the decision-making context: when to file, how to frame the message, the claim_token workflow, and operational constraints. An agent has everything needed to invoke it correctly and reason about post-call behavior.

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%, meeting the baseline of 3. The description adds important semantics not in the schema: claim_token must be passed 'with no other arguments' and the flow for reusing a returned token. Message length and specificity guidance also supplement 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 clear verb+resource ('Tell the Pipeworx team...'), then enumerates concrete use cases (bug, feature, data_gap, praise). It explicitly restricts scope to Pipeworx-served tools, distinguishing it from all sibling research, search, and subscription 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 explicitly states when to use the tool (bug, feature/data_gap, praise) and gives a clear exclusion: do not report issues with other MCP servers' tools, file with that server instead. It even helps disambiguate whether a tool belongs to Pipeworx, providing strong guidance for agent decision-making.

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 valuable context: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). This goes beyond the annotations to explain derivation and timeliness.

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

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

The description is two paragraphs: first sentence states purpose succinctly, then three bullet-like use cases, followed by notes on derivation and caching. Every sentence adds value without redundancy. Front-loaded and well structured.

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

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

Given one optional parameter, no output schema, and rich annotations, the description fully covers what the tool returns (top tools, packs, call volume), how it's derived, and caching. The agent can confidently understand and invoke the tool.

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

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

The single parameter (window) is fully covered by schema with enum and description. The description adds meaning by relating window length to behavior: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose appropriately.

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 trending tools, packs, and call volume on Pipeworx, with specific use cases. It distinguishes itself from sibling tools by focusing on aggregate usage trends rather than direct queries or entity profiles.

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

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

The description lists three explicit use cases (discovering hot data, confirming canonical tools, aligning use cases) that guide when to use. It does not explicitly mention when not to use or alternative tools, but the context is clear enough for an agent to self-select.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, consistent with safe read operations. The description greatly expands on behavioral traits: monotonicity violations, partition checks, Jaccard similarity filter (≥0.30), placeholder filtering (>20% placeholder fraction returns null), fill check against CLOB depth (realizable vs theoretical edge). No contradiction with annotations.

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

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

The description is verbose but each sentence adds value. It is front-loaded with core functionality and then provides necessary details. Could be slightly more concise without losing information, but overall well-structured for a complex tool.

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

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

Given no output schema, the description adequately defines the response structure: opportunities array with fields (gap_pp, suggested_trade, reasoning, monotonicity violation context) and partition_check object in event mode (sum_yes_prices, gap_from_1, placeholders_filtered, suggested_trade). Also covers fill_check results. All behavioral aspects are addressed, making it complete for an AI agent.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds substantial value beyond the schema: explains the logic behind event mode (walks child markets, date-axis/threshold-axis ordering, partition_check sum ≈1) and topic mode (searches related events, flattens markets, comparator on union, cross-event patterns). Provides concrete examples and details on internal filters (Jaccard, placeholder).

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 distinguishes three distinct invocation modes (no args, event, topic) with specific examples, making the purpose unambiguous.

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

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

Explicitly states when to use each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. Provides usage examples like slug 'fed-decision-may-2026' and seed question 'Strait of Hormuz...'. Also explains when not to trade (realizable_edge_pp ≤ 0) and suggests polymarket_fill_risk for custom sizing, guiding appropriate tool selection.

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

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

The description provides exhaustive detail on the five model families, response segments, edge calculations, slippage handling, caching behavior (1h KV), and diagnostics. It goes far beyond the annotations, fully disclosing what the tool does without any contradiction.

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

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

The description is well-structured with clear sections for model families, response segments, and knobs. However, it is rather verbose with extensive algorithmic detail (e.g., per-sport alpha values) that may be excessive for an agent. Still, it avoids redundancy and is front-loaded with 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?

With no output schema, the description fully covers the response structure (by_segment with three categories, diagnostics, Fed note, etc.) and the attributes of each opportunity. All 9 parameters are described in the schema, and the description ties them together holistically. The description is sufficient for an agent to understand inputs, behavior, and outputs.

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 descriptions are already detailed. The tool description adds context by grouping parameters into 'Tradeable-edge knobs' and explaining how they interact (e.g., min_liquidity and max_spread_pp filter realizable edges). This enhances understanding beyond the 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's purpose: scanning top Polymarket markets for opportunities where Pipeworx data disagrees with market price. It highlights the intended use case 'what should I bet on today' and distinguishes itself from siblings like polymarket_arbitrage by focusing on top markets and specific model segments.

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

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

The description mentions the tool is built for daily betting decisions and that it avoids paging through hundreds of markets, but it does not explicitly state when to use this tool versus alternative tools like polymarket_arbitrage or polymarket_edge_tracker. Usage context is implied but not clearly differentiated.

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

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

The description extensively details behavioral traits beyond the annotations: it explains the data sources (daily snapshots), response structure (tracked, expired, snapshot_dates), decay computation (edge_pp_net, sign by trade direction), and limitations (history depth, gap handling). This adds significant value over the readOnlyHint and other annotations.

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

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

The description is front-loaded with the core purpose and then details the response format and limitations. While it is lengthy, each sentence serves a purpose. It could be slightly tightened, but no extraneous information is present.

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 lack of an output schema, the description compensates by thoroughly explaining the response structure (tracked[], expired[], snapshot_dates[]) with sub-fields. It covers edge cases (expired opportunities, gaps in snapshots, decay sign) and provides limits (60-day TTL). This makes the tool's behavior fully understandable without an output schema.

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

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

The schema covers both parameters with descriptions (100% coverage), providing a baseline of 3. The description adds context: default values (14, '1wk'), allowed range for days (2-30), and explicit window options (24hr, 1wk, 1mo). This justifies a score of 4, as it goes slightly 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 identifies the tool as providing edge persistence and decay telemetry from daily snapshots, answering specific questions about edge duration and decay. It distinguishes itself from the sibling tool 'polymarket_edges' by focusing on historical tracking rather than raw edge 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?

The description explains when to use this tool: to determine if an edge is fresh or old and to understand decay. It implies that for raw edges, one should use polymarket_edges. The LIMITS section provides boundary conditions (60-day TTL, snapshot missing days), guiding appropriate usage. However, it does not explicitly list alternative tools for similar 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds significant behavioral context: it walks the order book ladder, details return fields (e.g., top_of_book, vwap_fill_price, slippage_pp, shares_filled, verdict), and warns about risks like unhedged directional positions and uncapturable theoretical overround on thin books.

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 bold headers for modes. Every sentence serves a purpose, explaining parameters, return fields, and usage guidance. While it is verbose, the complexity of the tool justifies the length. Some 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 (two modes, no output schema, multiple return fields, risk warnings), the description is remarkably complete. It covers all scenarios, explains the dominant loss mode, and provides actionable guidance for an AI agent. No gaps are evident.

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 the meaning of each parameter in context of the two modes, default values, and how 'size_usd' differs between single-market and basket (spend vs. settlement notional). This goes beyond the schema's brief descriptions.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishes between single-market and basket modes, and explicitly contrasts with sibling tools polymarket_arbitrage and polymarket_edges by specifying when to use this tool before acting on signals or trades above $500.

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: before acting on polymarket_arbitrage signals or any polymarket_edges trade above $500. Also provides conditional requirements (one of market or event) and explains consequences of not using it, such as partial basket fills converting an arb into an unhedged directional position.

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?

Even with strong read-only annotations, the description adds substantial behavioral context: compatibility codes can be non-empty even when pairs are returned, `null` temporal alignment means 'could not compute' rather than 'aligned', matches are keyword-based and unverified, Kalshi fees are not modeled, and skipped-leg counters expose dropped comparisons. This goes far beyond what annotations alone convey.

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

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

The description is long and dense, but it is well-labeled (TWO MODES, RESPONSE, SAFETY FIELDS, Codes) and nearly every sentence carries necessary caveats or contract details for a complex cross-venue comparison tool. It could be tightened, especially around the code list, but it is structured enough for an agent to parse the key rules.

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

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

With no output schema, the description carries the full burden of explaining response semantics, and it does so thoroughly: leg-by-leg prices, `top_spreads_pp`, `compatibility_warning`, `compatibility_codes[]`, per-entry flags, `temporal_alignment`, `fees_note`, and skipped counters are all defined. An agent has enough context to invoke the tool and interpret results correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real relational semantics: `topic` auto-fetches matching events, explicit parameters override the topic-mapped side, and both modes run the identical token-overlap matcher with the same disclosures. It also clarifies that all parameters are optional and how mode selection affects output 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 identifies the resource (cross-venue spread between Kalshi and Polymarket for the same question) and explains the tool's goal, including the signal caveat about equivalent bet shapes. It is not a tautology and adds meaningful scope, though it lacks an explicit imperative verb like 'returns' or 'computes' and does not directly distinguish itself from closely related siblings such as polymarket_arbitrage.

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

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

The description gives explicit mode-selection guidance: use `topic` for pre-mapped shortcuts or explicit `kalshi_event_ticker` + `polymarket_event_slug` for custom pairings, and notes both run the same matcher. It also warns that pre-mapped topics often return compatibility warnings and that spreads are gross, not net tradeable edges. It does not name alternative sibling tools or state hard when-not-to-use conditions.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds value by explaining scoping (anonymous IP, BYO key hash, or account ID) and the listing behavior when key is omitted. 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 two sentences long, well-structured, and front-loaded with the core purpose. Every sentence contributes useful information without redundancy.

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

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

For a simple tool with one optional parameter and no output schema, the description covers purpose, usage, scope, and relationship to sibling tools. It is fully adequate for an agent to understand when and how to invoke it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining that the value was 'previously saved via remember' and giving usage examples, which helps the agent understand the semantic context of the key parameter.

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 'retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', providing a specific verb and resource. It distinguishes from sibling tools remember and forget by mentioning pairing with them.

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

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

The description explains when to use the tool ('look up context the agent stored earlier') and gives concrete examples. It also references alternative actions save and delete via sibling tools, though it does not explicitly state when not to use this tool.

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

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

Adds detailed behavioral context beyond annotations: returns most recent alerts, includes specific fields (source, citation_uri, raw payload), describes mark_read behavior and filtering. 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 well-structured paragraph with front-loaded purpose, smooth transition to parameter details, and a closing note on alternative access. No redundant sentences.

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

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

No output schema, but description covers return fields (source, citation_uri, raw payload) and edge cases (mark_read effect on subsequent calls). Complete for a read-only list 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?

All five parameters are described in the schema (100% coverage). The description adds meaningful elaboration: explains filtering by type and since, mark_read flag behavior, and unread_only option.

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 'Pull fired events from your subscription feed' with a specific verb and resource. Mentions alternative access via REST endpoint, distinguishing from other 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 usage context: polling works fine, alternative access via REST. Does not explicitly state when not to use, but gives sufficient guidance for typical use.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds valuable transparency: it fans out to multiple sources (SEC, GDELT/GNews fallback, USPTO) with fallback logic and soft-fail details. It also describes the return structure (grouped changes, total count, 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 a single focused paragraph that front-loads example queries. Every sentence adds necessary information without redundancy. It is concise yet comprehensive, earning its place with zero wasted text.

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

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

Given the tool's moderate complexity (3 parameters, multiple data sources, no output schema), the description is complete. It explains the parallel fan-out to different sources, fallback behavior, return structure, and caveats (USPTO soft-fail). No gaps remain for agent decision-making.

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

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

Schema coverage is 100%, so baseline is 3. The description adds advisory detail: for 'since', it clarifies ISO date and relative formats and suggests '30d' or '1m'; for 'value', it explains ticker or CIK; for 'type', it notes only 'company' supported. This goes 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 starts with concrete example queries and states 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly identifies the tool's purpose and distinguishes it from the sibling tool 'entity_profile' by explicitly stating when to use that instead.

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 this tool versus 'entity_profile' for static profiles. The example queries illustrate typical use cases. While it doesn't differentiate from all other siblings, the guidance is clear and actionable.

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

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

Adds context beyond annotations: scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous. No contradiction with readOnlyHint (false) or destructiveHint (false).

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, front-loaded with purpose, every sentence earns its place. 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?

Tool is simple (2 params, no output schema); description covers purpose, usage, behavior, and pairing. Fully adequate.

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

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

Schema coverage is 100%, so baseline 3. Description provides example keys and values (e.g., resolved ticker, target address), adding slight value beyond schema.

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

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

States 'Save data the agent will need to reuse later' – clear verb+resource. Distinguishes from siblings like recall and forget by name and function.

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

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

Explicitly says 'Use when you discover something worth carrying forward' and pairs with recall and forget, guiding when to use and alternatives.

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

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

Despite annotations already marking the tool read-only and non-destructive, the description adds rich behavioral context: internal cascading through multiple lookup endpoints, graceful degradation when GLEIF or OpenFIGI is unavailable, returning figi_candidates and asserting nothing on ambiguous matches, and explicitly listing unresolved identifiers rather than omitting them. This goes well beyond the annotation hints.

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

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

The description is dense and information-rich, and almost all content earns its place for a complex resolution tool. However, the opening sentence is a very long run-on with nested parentheticals and many examples, so it is more heavy than concise; shorter, more front-loaded sentences would improve scannability.

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 present, the description carries the full burden of explaining return behavior, and it does so thoroughly: identifiers are source-labelled, unresolved IDs appear under unresolved, ambiguous matches return figi_candidates, and both company and drug result fields are specified. It also covers failure modes such as unavailable enrichment services and non-US issuers, leaving nothing critical unspecified.

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

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

The schema already describes both parameters, but the description materially extends them by revealing that company input accepts ISIN in addition to ticker/CIK/name, explaining the ISIN-to-LEI path, and warning that the agent must pass only the entity name, not the full noun phrase, because the FIGI lookup matches instrument names. This is high-value guidance beyond the property descriptions.

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

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

The description opens with concrete user phrasings and states a precise action: resolve a user-spoken NAME to the canonical/official identifiers other tools require as input. It enumerates supported entity types (company/drug) and explicitly positions itself as the tool to use first when a name needs an ID, which separates it from lookup/profile siblings.

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

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

'Use FIRST whenever you have a name but need an ID' gives an explicit triggering condition and situates the tool relative to downstream tools. However, it does not explicitly name sibling alternatives or explain when to choose lookup/entity_profile instead, so it stops short of a full when-to-use/when-not-to-use guide.

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 that it probes each entity, returns ranked list with score/confidence/signal density. No mention of potential rate limits from multiple probes, but overall transparent.

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, front-loaded with main action, no redundant words. Efficient and well-organized.

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?

Describes return format (ranked list with score, confidence, signal density) despite no output schema. Covers usage context and result structure adequately.

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. Description adds value by noting first entity is treated as 'subject' for narrative, which goes beyond schema.

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

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

Clearly states the tool compares AI visibility across multiple entities side-by-side, using 'ai_visibility_check' internally. Distinguishes from sibling 'ai_visibility_check' by being the multi-entity aggregation version.

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

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

Explicitly describes use case for competitive AI-marketing audits. Implies single-entity checks should use the sibling, but lacks explicit when-not or alternative instructions.

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 significant behavioral context beyond annotations: mentions partial failure degradation, bundlephobia latency (5-30s), and sources_failed field. No contradictions with annotations (readOnly, idempotent, openWorld, non-destructive).

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

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

Description is detailed but concise given the complexity. Front-loaded with purpose and provides all necessary information without redundancy. Slightly longer than ideal but 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?

No output schema exists, but description fully explains return structure: summary block fields, per-advisory detail, links, alternative versions. Also covers failure modes and latency, making it complete for the tool's complexity.

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

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

Schema coverage is 100% with clear schema descriptions. Description adds extra meaning: scoped packages accepted for 'package', and default behavior for 'version' (latest published version when omitted). Complements schema effectively.

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 a clear verb+resource: 'Composite should I add this npm package to my project check'. It explicitly states the ecosystem scope (NPM only) and distinguishes from alternatives like deps.dev for other ecosystems, which differentiates it 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?

Explicit guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also states when not to use (PyPI etc. fall under deps.dev:version), providing clear context and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable behavioral details: uses BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, 200K char cap with truncation and flagging. 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?

Five sentences, front-loaded with purpose. Each sentence adds unique value: purpose, use case, pairing, technical details, and limits. No redundancy or fluff.

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

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

Comprehensive given complexity: explains use case, technical mechanism, input constraints (200K chars), output format (passages with offsets and scores), and integration with sibling tool. Missing output schema is compensated by description of return values.

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

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

All three parameters are described in the schema (100% coverage). The description adds context: 'text' examples (SEC 10-K body), 'query' examples (supply-chain risk), and 'limit' default value. Adds 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 performs semantic search inside a fetched record, provides concrete examples (SEC 10-K body, article), and distinguishes from sibling tools like ask_pipeworx_grounded by explaining when to use it (when record is too large for prompt).

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded for grounding. Also mentions input cap and truncation, giving clear context for appropriate use.

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

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

Annotations indicate idempotent and non-destructive. Description adds substantial behavior: OAuth requirement, supported types with examples, delivery channel specifics (email, SMS, webhook with HMAC signing), and rate limits. No contradiction.

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

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

Description is well-structured but lengthy. Each sentence adds value, covering purpose, prerequisites, types, and delivery. Could be slightly tightened (e.g., bullet points for types), but overall clear and 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?

No output schema, but description states returns subscription id. For a creation tool, that may suffice. However, lacks details on full subscription object or confirmation response. Given complexity, it's largely 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 covers 100% but description enriches with type-specific examples for params (e.g., sec_8k with items codes) and delivery constraints (phone verification, 10/day cap, webhook signing secret). Adds practical guidance beyond 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This differentiates from sibling tools like list_subscriptions (which lists existing) and unsubscribe (which removes).

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 mentions prerequisites (Pipeworx OAuth account) and constraints (phone verification, rate limits). While it doesn't explicitly contrast with siblings, the purpose is clear for creation, and alternatives like recent_alerts and list_subscriptions are implied.

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 that it returns category-bucketed example questions with exact tool+argument shapes from a live catalog, providing extra context beyond the safe, read-only nature.

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 moderately concise with three sentences. It front-loads the purpose and usage, then adds detail. While every sentence adds value, it could be slightly tighter without losing information.

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

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

Given one optional parameter, rich annotations, and no output schema, the description fully covers the tool's purpose, usage, and return format (category-bucketed examples with tool shapes). It is complete for an onboarding 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 describes optional topic with examples. Description explains purpose (focus area), lists possible values, and clarifies default behavior (full spread). This adds significant meaning beyond the schema, which has 100% coverage.

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

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

The description clearly states the tool returns category-bucketed example questions to help users understand what to ask. It specifies the verb 'suggest questions' and the resource 'Pipeworx capabilities', and distinguishes it from siblings by positioning it as the onboarding entry point.

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

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

The description explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. It also implies alternatives (directly using ask_pipeworx etc.) when the user knows what to ask.

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=false, idempotentHint=true, destructiveHint=false. The description adds valuable context: ownership enforcement, that the row is deactivated not deleted, and that historical events stay available. This extends beyond annotations without contradiction.

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

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

The description is only two sentences, with the first immediately stating the action and target, and the second adding constraints and side effects. No superfluous words, 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?

For a simple mutation tool with one parameter and good annotations, the description covers the core action, ownership constraint, side effect of deactivation, and relevant sibling tool for historical data. It is fully sufficient for an AI agent to understand usage.

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

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

The input schema has 100% coverage with a clear description of the 'id' parameter. The description adds meaning by stating the id is a 'uuid returned by subscribe', clarifying its origin and usage 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 'Cancel a subscription by id.' using a specific verb and resource. It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by mentioning ownership enforcement and the deactivation behavior.

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

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

The description specifies that ownership is enforced, meaning only own subscriptions can be canceled. It also mentions that historical events remain available via 'recent_alerts', providing context for when to use this tool versus alternative tools for historical data. However, it does not explicitly list when not to use it or compare to other cancellation methods.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses critical behavioral traits: the two routing paths, the exact verdict enum, and the crucial distinction between could_not_verify (check did not happen) and unsupported (no source exists). The explicit warning that could_not_verify must not be shown as evidence is high-value transparency.

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

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

The description is longer than average but every sentence adds necessary detail: trigger phrases, routing rules, output format, error semantics, and efficiency rationale. It is front-loaded with examples and logically organized, making it easy to scan and apply without bloat.

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 must explain return values and does so thoroughly: verdict list, grounded/structured value with citation, reasoning, and error object for verification failures. It also covers edge cases (could_not_verify vs unsupported) and routes for both company-financial and other claims, making it complete for the tool's complexity.

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

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

Even though schema coverage is 100%, the description enriches both parameters: claim is already exemplified, and tolerance_pct gains real-world meaning (override implied tolerance, set 1–2 for hallucination detection, default cap of 5). This guidance is actionable and goes beyond the schema's basic type/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 defines the tool as natural-language claim verification with explicit trigger phrases ('fact check', 'verify the claim that…') and a specific outcome (verdict + evidence). It clearly distinguishes this from sibling research/entity tools by focusing on judging the truth of a stated claim rather than open-ended or comparative 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?

States 'Use whenever the agent needs to check whether something a user said is factually correct' and further splits guidance: company-financial claims take the structured SEC/XBRL path, all other claims use the grounded pipeline. It also positions the tool as a replacement for 4–6 sequential calls, indicating when it is the preferred single-call option.

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