Semver

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

Annotations already indicate readOnlyHint, idempotentHint, destructiveHint=false. Description adds that default model is free but Anthropic requires user's own API key and costs money. Also explains return structure (per-model score, confidence, signals, raw_response + combined view).

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

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

Single paragraph of ~60 words, front-loaded with main action. Every sentence adds value. No fluff.

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

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

No output schema, but description explains return format (per-model fields + combined view). All parameters are explained with practical context. Complexity is moderate and description covers enough for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. Description adds context: default model is Workers AI Llama-3.3-70b, _apiKey is needed for Anthropic, and context helps disambiguate. This 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?

Description clearly states verb 'Probe', resource 'LLMs', and output 'score visibility (0-100) per model'. It specifies default model and optional Anthropic key, making the tool's function 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 mentions use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring). Explains when to provide _apiKey and optional context. Does not explicitly mention 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 declare readOnlyHint, openWorldHint, idempotentHint; description adds that it routes to 4,770 tools, returns structured answers with citation URIs, and works on every tier. 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 front-loaded with key guidance ('PREFER OVER WEB SEARCH'), includes examples, and compares with siblings. Though lengthy, every sentence adds value.

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

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

Given no output schema, description explains return format (structured answer with citation URIs). Covers usage, alternatives, parameter aliases, and examples, making it fully self-contained for a complex tool.

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

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

Schema coverage is 100% with multiple aliases for question; description provides natural language usage and meaningful examples, adding context beyond schema.

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

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

The description clearly states it answers factual questions by routing to many sources, and explicitly distinguishes from siblings like ask_pipeworx_grounded and deep_research via 'Step up only when needed' guidance.

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 'PREFER OVER WEB SEARCH' and provides detailed when-to-use examples (e.g., SEC filings, FDA data, weather) and when to use alternatives (grounded, deep_research, breaking news).

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

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

The description discloses behavioral traits beyond annotations: it is hallucination-resistant, guarantees answer extraction only from tool result, and provides structured refusal reasons on failure. Annotations already indicate read-only, open-world, idempotent, and non-destructive; the description adds valuable context about behavior in error cases.

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

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

The description is a single paragraph of around 8 sentences, front-loaded with the main purpose and key differentiator. Every sentence adds value: purpose, mechanism, return format, usage guidelines, trade-off with sibling. No unnecessary words.

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

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

The description is contextually complete despite no output schema: it details the return format on success and failure, including specific refusal reasons. It explains the routing mechanism and cost trade-off. Given the tool's complexity and the richness of sibling tools, the description covers all necessary aspects.

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 clear descriptions for each parameter (question and aliases). The description does not add semantic meaning beyond what the schema provides, as it only mentions 'your question in natural language' which is already in the schema. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the mechanism (picks the right tool, fetches data, extracts answer from result only) and distinguishes from the sibling 'ask_pipeworx' by highlighting the extra LLM call and suitability for high-stakes 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?

Explicit usage guidance is provided: 'Use whenever an answer will be quoted, cited, or acted on...' with examples like financial verdicts, legal claims, medical lookups, public statements. It also explicitly advises preferring 'ask_pipeworx for casual lookups' due to the extra cost.

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 provides extensive behavioral details beyond annotations: fan-out logic per classifiers, resolver contract with match confidence, parent event extraction, news fallback handling, safety short-circuit for low confidence and closed markets, wide-spread tradeability notes, and resolution-rule risk. All disclosures are consistent with annotations (readOnlyHint, idempotentHint, 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?

The description is long but well-structured with section headers and examples. Every sentence provides useful information, but the length may make it less concise for quick scanning. It balances detail with organization.

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

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

Given the tool's complexity (multiple classifiers, fan-out, resolver logic, safety checks), the description covers key aspects thoroughly. No output schema exists, but the description explains return shapes (market, analysis, evidence, resolver, parent_event, news). Missing concrete examples for every classifier, but the coverage is sufficient.

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

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

Schema description coverage is 100%. The description adds context for the 'market' parameter (slug, URL, question text) and for 'include_raw' (purpose of raw vs summarized). 'depth' is adequately described in schema. Overall, description adds meaningful extra info 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 states a clear verb ('Research a Polymarket bet...') and resource (Polymarket bet), and distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on data retrieval. The scope is well-defined: pulling Pipeworx data in one call.

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

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

Explicit usage guidelines are given: 'Use for should I bet on X, what does the data say about Y, or is there edge in Z.' It also explains when to inspect resolver results before trusting analysis, and mentions blocking paths (low_confidence_match, market_closed_or_inactive). However, it does not explicitly state when not to use this tool compared to siblings.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: pulls latest 10-K data, handles off-calendar fiscal years, sorts results by primary metric, returns paired data plus 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 effective but slightly verbose. It is front-loaded with example queries and key instructions. Could be trimmed slightly without loss of clarity, but overall well-structured.

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

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

Given the complexity (two entity types, data sources, sorting, return format), the description is highly complete. It explains what data is pulled for each type, how results are sorted, and that it returns paired data with citation URIs. No output schema, but the description adequately covers return expectations.

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

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

Schema coverage is 100%. The description adds meaning beyond the schema: explains that type='company' pulls specific financials (revenue, net income, cash, debt) from SEC EDGAR/XBRL, and type='drug' pulls FAERS counts, FDA approvals, trial counts. It also clarifies that values should be tickers/CIKs or drug names.

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

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

The description clearly states the tool does side-by-side comparison of 2-5 companies or drugs in one parallel call. It provides example queries like 'Compare X and Y' and explicitly contrasts with sequential lookups, making the purpose unambiguous.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example queries. It does not explicitly state when not to use it, but the strong preference is clear and sufficient for 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 readOnly, idempotent, non-destructive behavior. The description adds value by specifying the return format and that prerelease precedence is honored. 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?

Single sentence, directly conveys action and result, no extraneous words. Front-loaded and 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 no output schema, the description adequately explains return values. Parameters are clear from schema. Lacks examples or error handling, but for a simple comparison tool, it is sufficient.

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

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

Schema coverage is 100% with basic descriptions 'First version.' and 'Second version.'. The tool description does not add further semantics beyond the schema, which is adequate but not enhanced.

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 (compare), the resource (semver strings), and specifies the return values (-1, 0, 1) with prerelease precedence. It distinguishes from sibling tools like parse_semver and satisfies_range effectively.

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

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

The description implies usage for comparing two semver strings, which is clear from the purpose. However, it does not explicitly mention when not to use it or provide direct comparisons to alternatives, though differentiation is achieved through the purpose alone.

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

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

Beyond annotations (readOnly, openWorld, idempotent), description adds account auth, parallel execution, return format (evidence, confidence, gaps), expected time, and behavior for out-of-scope topics. No contradiction with annotations.

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

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

Description is lengthy but front-loaded with critical info (account requirement, alternatives). Every sentence provides essential context for correct usage. Could be slightly more compact but appropriate for tool complexity.

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

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

Given no output schema, description explains return packet contents (verbatim evidence, confidence, source, timestamps, citations, gaps). Covers limitations (breaking news leads to empty gaps) and expected response time. Complete for effective use.

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

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

Schema coverage is 100% with descriptions. Description adds non-obvious context: depth maps to facet counts (quick=3, standard=5, thorough=8) and paid plan restriction for thorough. This goes beyond basic schema info.

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

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

The description precisely states it performs grounded multi-source research across structured data, decomposing questions into facets and returning a findings packet. It clearly distinguishes itself from siblings like ask_pipeworx by contrasting use cases.

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 (broad/multi-part questions over structured data) and when not (single lookups, breaking news). Names alternatives (ask_pipeworx) and mentions account/plan requirements.

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 readOnlyHint=True, idempotentHint=True, destructiveHint=False. The description adds that the tool returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed,' which provides valuable behavioral context beyond annotations.

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

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

The description is four sentences long and well-structured: it starts with purpose, lists domains, explains return format, then provides usage guidance. Each sentence adds value, though it could be slightly more concise.

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

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

Given no output schema, the description adequately explains what the tool returns (names, descriptions, full input schemas). It also covers purpose, usage guidance, and domain list. It does not explain edge cases or error handling, but overall is sufficiently complete for an agent to use 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 description coverage is 100% (all 6 parameters described). The description does not add significant parameter semantics beyond the schema, but it provides example queries and clarifies that 'query' accepts aliases. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains and explains what is returned (top-N tools with names, descriptions, schemas). It distinguishes from siblings by saying 'Call this FIRST.'

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: 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This provides clear context and exclusion criteria.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals important behaviors: it fans out across multiple sources in parallel, includes soft-fail for USPTO patents after May 2025, and uses fallback mechanisms (GDELT→GNews). It also details the return structure.

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 fairly long but front-loaded with examples and key guidance. Each sentence adds relevant information, though some redundancy with schema descriptions could be trimmed. Overall it is well-structured and 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 complexity of the tool (multiple data sources, fallback, soft-fail, specific return types), the description is thorough. It covers what is returned (filings, fundamentals, patents, news, LEI) and addresses limitations (patent sunset, name input). Without an output schema, the description fully compensates.

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 already descriptive parameter comments. The description adds value by reinforcing that 'value' accepts ticker or zero-padded CIK, explaining why names aren't supported, and suggesting `resolve_entity` as an alternative. This is a moderate improvement over 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: 'full cross-source profile of a US public company in ONE parallel call.' It provides numerous example queries and explicitly distinguishes it from chaining single-pack lookups, which is a key differentiator from sibling tools.

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

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

The description explicitly states when to use this tool ('ALWAYS PREFER over chaining single-pack...' for holistic views) and when not to use it ('Names not supported — use resolve_entity first'). It also notes future support for person/place. This gives clear usage context.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data and the purpose of deletion, which is useful beyond the structured annotations.

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

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

The description is two sentences plus a usage phrase, front-loaded with the core action. No wasted words; every sentence provides value.

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

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

For a simple tool with one parameter and no output schema, the description adequately covers purpose, usage, and behavioral context. It could mention exact key matching but is complete enough.

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 parameter description 'Memory key to delete.' The description adds only the phrase 'previously stored,' which is implicit. It does not significantly enhance the schema 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 starts with 'Delete a previously stored memory by key,' which is a specific verb (delete) and resource (memory by key). It distinguishes from siblings by explicitly pairing with 'remember and recall.'

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

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

The description provides explicit when-to-use scenarios: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names alternatives/companions: 'Pair with remember and recall.'

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

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds detail about fetching the page, extracting title/description/key links, and emitting standard llms.txt format. No contradictions with annotations.

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

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

The description is three sentences, front-loaded with purpose, followed by behavior and use cases. Every sentence contributes value with no redundant or vague wording.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations, the description covers purpose, behavior, output format, and use cases adequately. It is complete for an agent to 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?

Schema coverage is 100%, so baseline is 3. The description does not add additional semantic meaning beyond what the schema provides; it only mentions 'for any URL' without further elaboration on parameters.

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

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

The description clearly states the verb 'generate', the resource 'llms.txt file', and the context 'for any URL'. It specifies the target AI crawlers and the output format, distinguishing it from sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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

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

The description lists three specific use cases: getting a client's site indexed, drafting for your own project, or auditing a competitor's site. This provides clear positive guidance, though it does not explicitly exclude alternative 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond annotations by specifying that it returns certain fields and defaults to active-only subscriptions, which is useful for the agent.

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

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

The description is extremely concise: two sentences with no filler. The first sentence states purpose and output, the second gives usage guidance. Every word earns its place.

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

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

Despite no output schema, the description explicitly lists return fields. Combined with strong annotations and a single optional parameter, the description covers purpose, output, defaults, and usage context completely for a simple 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 baseline is 3. The description adds value by explaining the default behavior (active only) and implying the parameter's effect ('include_inactive' to include cancelled), which goes beyond the schema's simple description.

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

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

The description clearly states 'List the caller's active subscriptions' with a specific verb and resource, and it lists the exact return fields, distinguishing it from sibling tools like 'subscribe' and 'unsubscribe'.

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

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

The description provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use the tool but does not specify when not to use it or list alternatives by name.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the agent knows it's safe. The description adds that the tool is 'keyless, offline', indicating no network calls or side effects, which complements the annotations without contradiction.

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

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

Two sentences, no redundant information. Every word adds value: 'keyless, offline' conveys behavior, 'Accepts an optional leading 'v'' clarifies input format. Perfectly concise.

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

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

For a simple parsing tool with only one parameter and no output schema, the description fully covers input format and output components. No additional information is needed given the task simplicity.

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

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

Schema description coverage is 100% with a clear example. The description adds that an optional leading 'v' is accepted, which is not in the schema. This provides useful semantic detail beyond the schema's basic type and example.

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

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

The description clearly states the verb 'Parse', the resource 'semantic-version string', and the output components 'major/minor/patch/prerelease/build'. It also distinguishes itself from sibling tools like 'compare_semver' and 'satisfies_range' by focusing on parsing rather than comparison or range checking.

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

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

The description implies usage for parsing version strings but does not explicitly state when not to use this tool or mention alternatives. However, the context of sibling tools provides implicit differentiation. The 'keyless, offline' note suggests no external dependencies, which is helpful.

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

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

Annotations are all false. Description adds important behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against quota, team reads digests daily, feedback affects roadmap. This supplements 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?

The description is concise, front-loaded with purpose, and provides critical usage details in a single paragraph without extraneous content.

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

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

Given the tool's simplicity (3 params, 2 required), the description covers all needed aspects: purpose, usage, rate limits, and quota. No output schema, but return value is implied. Slightly brief on feedback processing, but sufficient.

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

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

Schema description coverage is 100%, so the schema already describes parameters adequately. The description does not add significant new meaning beyond what's in the schema, but provides usage context in the main text.

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

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

The title and description clearly state it is for sending feedback to the Pipeworx team. It specifies types (bug, feature, data_gap, praise) and differentiates from sibling tools which are research and analysis focused.

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: for bugs, missing features, data gaps, or praise. It provides guidance on what to include (e.g., describe in terms of tools/packs). No explicit when-not-to-use, but it is unique among siblings.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral details: derived from CF analytics-engine, no PII, cached 5min-1h depending on window. No contradiction with annotations.

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

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

The description is three sentences plus a bulleted list of use cases, clear and front-loaded with main purpose. Slightly verbose in the third use case 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?

The description lacks detail on the output format (e.g., exact structure of returned data). While it mentions the type of content returned, no output schema is provided, and the description does not fully compensate for that 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 coverage is 100% with one parameter 'window' having a clear description in schema. The description adds extra meaning by explaining how window length affects results ('hot right now' vs 'steady-state demand'), improving usability beyond schema alone.

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

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

The description clearly states the tool returns 'top tools, top packs, and total call volume' with specific verbs ('returns', 'discovering', 'confirming', 'seeing'). It distinguishes from sibling tools by focusing on trending usage, which is unique among the listed tools.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical choice, seeing alignment) and clarifies the data is self-aggregating with no PII. It does not explicitly state when not to use or name alternatives, but the context makes it 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 mark readOnlyHint=true, but the description adds rich behavioral context: semantic anchor with Jaccard similarity (>=0.30), partition filter dropping placeholder slugs, fill check against live CLOB depth, and detailed explanation of arbitrage signals. 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 quite long but well-structured with clear sections for event mode, topic mode, semantic anchor, partition filter, and fill check. It is front-loaded with the main purpose. While some details could be condensed, the complexity of the tool justifies the length.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains the response structure (opportunities[], partition_check, fill check), edge cases (skipped_low_similarity, placeholders), and the logic behind arbitrage detection. It is very complete.

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

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

Schema coverage is 100% for both parameters, but the description adds significant extra meaning: event accepts slug or full URL, topic is a seed question; explains how each parameter affects behavior (single-event vs cross-event). Also describes the no-argument trending scan.

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 arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks'. It distinguishes between trending scan, event mode, and topic mode, and differentiates itself from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly tells when to use each mode: no args for trending scan, event for specific market, topic for cross-event scanning. It recommends event mode and warns when not to trade (if reazliable_edge_pp <= 0). It also suggests using polymarket_fill_risk for custom sizing.

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

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

Beyond annotations (readOnly, idempotent), the description reveals extensive behavioral details: caching at KV level keyed on all knobs, response structure with by_segment and _diagnostics, per-leg Kelly computation, tradeable-edge knobs, and why partition_overround parent Kelly is zero. This exceeds what annotations provide.

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

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

The description is lengthy but well-structured, starting with the core purpose and then detailing model families, response fields, and knobs. It front-loads the main use case. While some sentences are technical, every sentence adds value for an agent that needs full behavioral understanding.

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 of the tool and the absence of an output schema, the description thoroughly covers response fields: by_segment segments, diagnostics explaining why segments are empty, and field details like edge_pp_net and 24h-move warning. This ensures an agent can fully interpret the output without additional documentation.

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

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

All 9 parameters have schema descriptions, but the tool description adds significant context, e.g., explaining min_partition_leg_kelly compensates for min_kelly not filtering partition arbs, and that slippage_pp subtracts from raw edge. This extra value justifies a score above the baseline of 3.

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

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

Description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, specifically for 'what should I bet on today'. It distinguishes the tool's functionality from a generic market scan by specifying the disagreement detection and the model families used.

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

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

The description explicitly states the tool is for discovering betting opportunities without paging through hundreds of markets, and includes a note about Fed bets being excluded. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage or polymarket_edge_tracker, leaving some ambiguity about when to use this vs. alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the description does not need to repeat these. The description adds transparency about how trends and decay are computed, data gaps (cache-miss), and the meaning of output fields. No contradictions with annotations.

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

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

The description is detailed but efficiently structured. It front-loads the core purpose and then explains outputs and limitations. Some redundancy exists (e.g., default values repeated from schema), but overall it is well-organized and informative. Could be slightly shortened by relying on schema defaults.

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 (edge persistence, trends, decay) and the absence of an output schema, the description is highly complete. It covers input parameters, output structure (tracked, expired, snapshot_dates), interpretation tips (e.g., negative edge_pp_net = SELL YES), data sources, and limitations. No gaps remain 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?

Schema coverage is 100% with both parameters described. The description adds context by repeating default values (days: 14, window: '1wk'), clarifying the clamp range for days (2-30), and explaining the window family concept. It also describes the response structure, which adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question about edge longevity and contrast between fresh and old edges. It distinguishes itself from sibling tool polymarket_edges by using snapshots and providing derived analytics.

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 when to use the tool (understanding edge persistence and decay) and contrasts fresh vs old edges. It mentions limitations (60-day TTL, daily closes not intraday). While it doesn't explicitly say when not to use or list alternatives, the context implies that polymarket_edges is the raw data source. This provides adequate 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 (readOnlyHint, idempotentHint) are consistent with a read-only risk check. The description adds significant context: it walks the order-book ladder, returns verdict and risk metrics, explains clamping on size_usd, and warns about forced directional risk. 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 well-structured with sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Every sentence is informative. Slightly long due to complexity, but appropriately front-loaded and clear without excess.

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

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

Without an output schema, the description fully explains return values for both modes (e.g., top_of_book, slippage, verdict for single-market; theoretical_sum, capture_ratio, thin_legs for basket). It covers all necessary context for a complex, two-mode 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%, setting baseline at 3. The description enriches parameters by explaining mode-specific semantics (e.g., size_usd as spend vs target proceeds vs settlement notional) and default side auto-detection for basket mode, adding value beyond the schema.

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

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

The description clearly states the tool checks realizable vs theoretical edge against live CLOB order-book depth, distinguishes single-market and basket modes, and lists specific outputs. It explicitly differentiates from siblings by advising use before polymarket_arbitrage or polymarket_edges trades, making purpose unambiguous.

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

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

The description provides explicit when-to-use conditions (before acting on arb signals or edge trades above ~$500), explains why (thin books uncapturable, partial fills cause directional exposure), and specifies requirements (one of market or event) with defaults. It offers clear context without being redundant.

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

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

The annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds rich behavioral details: compatibility warnings, temporal alignment checks, skipped cross-type/subtype counters, and warnings about pre-mapped topics not being tradeable. This fully discloses the tool's limitations and edge cases.

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

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

The description is long but well-structured with sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every sentence adds meaningful information, and the core purpose is front-loaded. While it could be slightly more concise, the complexity justifies the length.

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

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

Given no output schema, the description compensates by detailing response fields (leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters). It covers input modes, response structure, safety warnings, and limitations, making the tool fully understandable.

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. The tool description adds value by explaining the topic parameter's 10 shortcuts, and providing example formats for explicit tickers. It also clarifies mode selection, 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 computes the cross-venue spread between Kalshi and Polymarket. It specifies two modes (topic shortcuts and explicit tickers), leaving no ambiguity about its function. The purpose is distinct from sibling tools, which focus on single-venue 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 explains when to use each mode and provides context about pre-mapped topics often returning compatibility warnings. However, it does not explicitly mention when to use alternative tools like polymarket_arbitrage, nor does it provide strict inclusion/exclusion criteria.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds scoping detail ('Scoped to your identifier'). Could elaborate on error behavior but sufficient.

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, no wasted words. Each sentence adds value.

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

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

Fully explains purpose, usage, scoping, and relationship to siblings. No output schema needed; completeness is high.

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 descriptions in schema already cover param behavior. Description adds example usage but same info; baseline 3 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 the tool retrieves a previously saved value (via remember) or lists all keys. Distinguishes from siblings by explicitly pairing with remember and forget.

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

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

Provides explicit usage context: 'Use to look up context the agent stored earlier… without re-deriving it from scratch.' Also mentions pairing with siblings for save/delete.

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, and non-destructive. Description adds behavioral detail about the persisted feed and how mark_read affects subsequent calls, enhancing transparency beyond annotations.

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

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

The description is front-loaded with purpose and provides necessary details in a structured way. It could be slightly more concise, but every sentence adds value.

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

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

Given no output schema, the description explains return values and usage patterns. It covers all parameters implicitly and provides alternative access method, making it fairly complete.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by giving an example type ('sec_8k') and clarifying that mark_read flags events as read, which slightly enhances understanding.

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

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

The description clearly states the tool pulls fired events from the subscription feed, specifying what each event carries. It is specific about the resource and action, but does not explicitly differentiate 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?

Provides guidance on filtering by type and since, and explains mark_read behavior. Mentions polling works and gives an alternative URL for scripts/dashboards, giving context on when to use the 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?

Annotations declare read-only and idempotent; description adds detailed fan-out logic to three sources, fallback behavior (GDELT→GNews on rate-limit/5xx), USPTO soft-fail explanation, and return structure (changes[] grouped by source, total_changes count, pipeworx:// URIs). No contradictions.

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

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

Single paragraph is dense but well-structured: query examples front-loaded, then fan-out description, then parameter explanations, then return structure, then sibling guidance. Every sentence adds value, though readability could slightly benefit from bullet points.

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 3 required params and no output schema, the description fully covers input semantics, multi-source behavior with fallbacks, and return format. Includes technical details like API sunset dates and soft-fail behavior, leaving no significant gaps.

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

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

Schema coverage is 100%, but description adds crucial context: ISO vs relative syntax for 'since' with examples ('7d', '30d', '3m', '1y') and recommended values; 'value' explains ticker or zero-padded CIK with format example; 'type' enum is explained as only 'company' supported.

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 ('change feed') and resources ('company's SEC EDGAR, GDELT→GNews, USPTO') with clear scope (time window). Distinguishes from sibling tool 'entity_profile' by contrasting use cases.

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

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

Explicitly tells when to use ('What's new with X' queries) and when not to ('Use entity_profile instead for static profile'). Provides a clear alternative and typical monitoring recommendation ('30d' or '1m').

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 idempotentHint=true and destructiveHint=false. The description adds behavioral context: key-value scoping, persistence (authenticated vs anonymous sessions), and pairing with other tools. 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?

Three sentences, front-loaded with purpose, each sentence adds value without redundancy. No wasted words.

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

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

Given no output schema and a store operation, the description adequately covers behavior (scoping, persistence, pairing). Could mention limits like key length, but overall complete for the tool's simplicity.

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

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

Schema coverage is 100% with good descriptions for key and value. Description reinforces the key-value nature and provides examples, but adds minimal new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool saves data for later reuse, specifying the resource (key-value pair) and distinguishing it from sibling tools (recall, forget). The verb 'save' and resource 'data' are specific.

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

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

The description explicitly advises when to use (when discovering something worth carrying forward) and mentions pairing with recall and forget. It explains scoping and persistence but does not explicitly state when not to use, though context implies appropriate use cases.

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

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

Discloses internal cascading through multiple lookup endpoints, adding context beyond annotations (which already indicate safe, read-only, idempotent behavior). 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?

Concise yet comprehensive, front-loaded with examples, then directive, then type details. Every sentence provides value without redundancy.

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

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

Covers return values for both types (no output schema), input formats, and internal cascading. Missing error handling or not-found behavior, but otherwise 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?

Adds significant meaning beyond the schema: explains return values per type (ticker+CIK for company, RxCUI for drug) and mentions auto-disambiguation. Schema coverage is 100% but description enriches it.

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: resolving user-spoken names to canonical identifiers. It provides example queries and details for each supported type, distinguishing it from siblings like 'entity_profile' and 'compare_entities'.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides context on when to use but does not mention alternatives or when not to use, though the directive is strong enough.

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

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

The description details the range syntax and acceptable operators, which adds context beyond the annotations (which already indicate read-only, idempotent, non-destructive behavior). This helps the agent understand the tool's behavior precisely.

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, concise sentence that front-loads the purpose and lists supported operators, followed by a helpful example. Every word earns its place.

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

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

Given the simple two-parameter input and no output schema, the description is nearly complete. It explains the input format clearly. It does not explicitly state the return type (presumably boolean), but the name and example strongly imply it, so the gap is minor.

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

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

Schema coverage is 100%, with both parameters described. The description adds value by explaining the range format and giving an example, enriching the semantic understanding beyond the schema definitions.

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

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

The description clearly states the verb 'Test' and the resource 'whether a version satisfies a range'. It lists the supported operators (exact, caret, tilde, comparators, x-ranges, AND, OR) and provides an example, making the purpose unambiguous and distinguishing it from sibling tools like compare_semver or parse_semver.

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 does not explicitly state when to use this tool versus alternatives like compare_semver or validate_claim. Usage is implied from the purpose, but no guidance on when not to use it or which scenarios are appropriate is provided.

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 valuable behavioral details: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and signal density. 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 concise and front-loaded: first sentence states the action, second explains the process, third gives a use case, fourth mentions output. Every sentence adds value without 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?

Without an output schema, the description sufficiently describes the return structure (ranked list with score, confidence, signal density). It covers the overall process and purpose. It could include limitations or error scenarios, but is adequate for agent selection.

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 parameters are well-documented. The description adds extra meaning: the first entity in the array is treated as the 'subject' for narrative, and the context parameter applies to every probe. 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 clearly states it compares AI visibility across multiple entities side-by-side, using ai_visibility_check internally, and ranks results. It explicitly distinguishes from a single-entity check by emphasizing multiple entities and competitive 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 a clear use case ('competitive AI-marketing audits') and an example question. It implies when to use this tool over siblings like ai_visibility_check (single entity) or compare_entities (general comparison). However, it does not explicitly state when not to use it or mention alternatives beyond the internal reference to ai_visibility_check.

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

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

Discloses timing behavior (5-30s first measurement), graceful degradation (sources_failed list), and return structure, complementing annotations that indicate safety and idempotency.

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

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

Every sentence earns its place: core purpose first, then usage, then behavioral details. 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?

Thoroughly describes return fields, error handling, and sources, compensating for lack of output schema. Covers all necessary context for an agent to use effectively.

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?

Adds meaning beyond schema: package parameter notes scoped packages accepted, version parameter clarifies default to latest, improving usability.

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

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

Clearly states it performs a composite safety/popularity/size check for npm packages, distinguishing it from sibling tools like compare_semver or parse_semver by describing the unified call.

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

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

Provides explicit when-to-use examples ('is X safe / popular / small') and when-not-to (non-npm ecosystems), directing to alternative deps.dev:version.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds specific technical details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K char cap with truncation flagging. This transparency goes beyond annotations, helping the agent understand behavior and limitations.

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: first states purpose, second provides usage guidance, third adds technical details. It is front-loaded, efficient, and contains no filler.

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

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

Despite lacking an output schema, the description clearly states what is returned (top-N passages with character offsets and similarity scores). It covers purpose, usage, technical constraints, and pairing with a sibling tool. For a tool with three parameters and no complex nesting, this is fully adequate.

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

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

Schema description coverage is 100%, so the schema already documents parameters well. The description repeats some of that information (e.g., max ~200K chars, query as natural-language) but does not add significant new semantics. It explains the output format (offsets, similarity scores) which indirectly clarifies parameter utility.

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 semantic search inside a fetched record, using a natural-language query to return top-N passages with offsets and similarity scores. It distinguishes itself from sibling tools like ask_pipeworx_grounded by emphasizing its use for in-document search after fetching the text.

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

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

The description explicitly says when to use: 'Use when the record is too big to cram into the prompt.' It also provides guidance on how it pairs with ask_pipeworx_grounded, offering an alternative workflow. This is highly actionable for an AI 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?

The description adds significant behavioral context beyond annotations: account requirements (OAuth, no anonymous/BYO), delivery limitations (SMS cap, webhook auto-disable), and channel details. 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 detailed yet well-structured, with clear separation of type, params, and delivery. 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?

Given the tool's complexity (nested objects, no output schema), the description adequately covers types, parameters, delivery, and prerequisites. Return value is briefly mentioned, which is acceptable.

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

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

Schema coverage is 100%, but the description enriches parameter meaning with examples, constraints, and use cases (e.g., items codes, topic, delivery validation). It adds value beyond the schema definitions.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe.

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

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

The description provides explicit context for when to use (proactive monitoring), outlines supported types and delivery channels, and implies alternatives. It lacks explicit 'when not to use' instructions but overall offers clear 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, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: returns category-bucketed examples with exact tool calls, drawn from live catalog, and that it is an onboarding entry point. 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 front-loaded with example queries, explains what it does and how to use. Each sentence adds value, though slightly lengthy. 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?

Despite no output schema, description fully explains return format (category-bucketed example questions with tool+argument shapes). Includes catalog size. 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 has 100% coverage with optional 'topic' parameter description. Description adds value by listing example topics and explaining that omitting gives full spread, focusing with topic. Goes beyond schema baseline.

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

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

Description clearly states the tool is the onboarding entry point for a new agent, returning category-bucketed example questions. It distinguishes from siblings like ask_pipeworx and discover_tools by specifying it provides examples with exact tool+argument shapes.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Provides guidance on optional topic parameter for focus, but does not explicitly state when not to use it.

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

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

Discloses ownership enforcement and deactivation (not deletion), which adds behavioral context beyond annotations. Annotations indicate idempotent and not destructive, aligning with the description. No contradiction.

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

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

Two sentences, no redundancy, front-loaded with the main action. Every sentence adds value.

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

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

Given the single parameter, no output schema, and informative annotations, the description is complete. It covers usage, ownership, side effects, and relation to sibling tools.

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 parameter 'id' is fully documented. The description does not add further meaning beyond the schema. 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?

Description clearly states 'Cancel a subscription by id.' The verb 'cancel' and resource 'subscription' are specific. It distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), guiding when to use and when not. Also explains the deactivation behavior and how historical events remain accessible via 'recent_alerts', offering an alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds valuable context: it reveals the exact data source (SEC EDGAR + XBRL), the output structure (verdict, structured form, actual value, citation, percent delta), and the scope limitation (v1 supports company-financial). No contradictions with annotations.

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

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

The description is concise—about 80 words—and front-loads the purpose with example queries. It packs scope, output, and advantage into one paragraph. Could be slightly improved with bullet points for readability, but no unnecessary 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?

Given the tool has one parameter, no output schema, and rich annotations, the description covers all essential aspects: input form, output elements (verdict types, citation, delta), scope, and even the internal replacement of multiple calls. It is complete enough for an AI agent to decide when and how to use it.

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

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

Schema description coverage is 100% (the single parameter 'claim' has a description). The description goes beyond by providing natural-language examples and showing expected user phrasings. It adds context for how the parameter should be formulated, which is useful for the agent.

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

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

The description uses specific verbs like 'validate', 'verify', 'check' and explicitly defines the resource: natural-language claims against authoritative sources. It distinguishes from siblings by listing exact user phrasings and scope (company-financial claims). It also states it replaces 4-6 sequential calls, which no sibling does.

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

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

The description clearly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples of user intents. However, it does not explicitly exclude other claim types (e.g., historical, scientific) or mention alternative tools for those, leaving some ambiguity.

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