H1b

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

Annotations indicate read-only, open-world, idempotent, non-destructive. The description adds that the default model is free, but using Anthropic requires a BYO API key (paid separately). It also explains the return structure (per-model score, confidence, signals, raw_response + combined view). 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, each carrying distinct information: what it does, default model and key behavior, and use cases. No fluff, front-loaded with action.

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

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

For a tool with 4 parameters and no output schema, the description fully explains inputs and outputs. It covers return format and usage scenarios, making it self-contained for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: default model is Workers AI Llama-3.3-70b (free), _apiKey is passed directly to Anthropic, and context helps disambiguate. This significantly enriches parameter understanding.

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

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

The description uses specific verbs ('probe', 'score') and a clear resource ('LLMs for what they know about a business/brand/product/topic'). It distinguishes itself from similar tools by focusing on visibility scoring per model, and the sibling list includes 'scan_competitor_ai_presence' which likely differs in scope.

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 useful for 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not provide explicit 'when not to use' or alternative tools, but it gives clear context and usage 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?

Beyond the annotations (read-only, idempotent, open-world), the description reveals internal behavior: it routes to one of 5,529 tools, fills arguments, returns stable citation URIs, and works on every tier. It also clarifies that it handles news and live feeds, which adds context not covered by annotations.

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

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

Although long, every sentence earns its place: usage directives, domain list, examples, and step-up alternatives are all tightly packed. The description is well-structured with clear signposts and no fluff, justified given the tool's role as a default entry point.

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

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

For a complex tool with no output schema, the description explains the return format (structured answer with citations) and covers all necessary context: when to use, when not to use, examples, and limitations. It also mentions speed and tier availability, making it complete for an agent to select and invoke 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?

The schema already documents all six parameters as alias strings with 100% coverage, so the baseline is 3. The description adds value by providing concrete examples of valid questions and trigger phrases, but it does not introduce new constraints or format details beyond the schema.

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

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

The description clearly identifies the tool as a natural-language question router that returns structured answers with citations across thousands of sources. It lists specific domains and examples, and explicitly distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description provides explicit when-to-use guidance, including trigger phrases and example questions. It says 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', and explicitly names alternatives for specific use cases (grounded for verbatim evidence, deep_research for broad/multi-part questions).

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description goes beyond by disclosing the beta nature, experimental candidate routing, the fact that no candidate is currently active (with a retirement date), and that results are compared to decide merges. This provides meaningful context about potential variability and operational state without contradicting annotations.

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

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

The description is front-loaded with the core beta identification and includes relevant specifics like tool count, arguments, and response shape. Some redundancy exists ('Falls back to nothing — this IS a full working router' restates earlier points), and the specific retirement date is extra detail, but overall it is reasonably compact and each sentence contributes useful context.

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

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

Given the tool has a single parameter, no output schema, and strong annotations, the description supplies essential context: purpose, usage, beta/experimental status, and relationship to ask_pipeworx. It does not detail the response shape beyond referencing ask_pipeworx's, but the reference to 'same response shape' and 'full working router' is adequate for a selection decision, especially since the tool routes across many 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%, with the single 'question' parameter and all aliases exhaustively documented. The description does not add parameter-specific meaning, which is acceptable given the schema already fully covers semantics. This meets the baseline for high coverage.

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

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

The description clearly states this is a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes from the stable ask_pipeworx sibling by framing itself as the experimental edge, and the verb 'ask' plus 'use it exactly like ask_pipeworx' clarifies its query/routing purpose.

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

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

The description provides explicit guidance: 'Use it exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It also notes that no candidate is currently active, so it matches ask_pipeworx exactly, and explicitly names the alternative ask_pipeworx. This covers when to use and which alternative to consider.

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

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

Beyond the readOnly/idempotent annotations, the description discloses return structure ({answer, evidence, confidence, source, fetched_at, refusal_reason}), refusal reasons, grounding behavior ('using ONLY what the tool result contains'), and an extra LLM call cost. 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 front-loaded with the key differentiator and every sentence adds value—covering mode, routing, limitations, use cases, refusal reasons, and cost trade-off. It is detailed but not bloated.

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 schema (only a question parameter) and the presence of annotations, the description fully covers when to use it, what to expect (evidence, confidence, refusal reasons), and how it relates to the sibling ask_pipeworx. No significant gaps remain for correct invocation.

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

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

The input schema already provides 100% coverage of the parameters, all aliases for 'question' with descriptions. The tool description adds no additional parameter-specific meaning, so the baseline of 3 is appropriate.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explicitly ties to routing from ask_pipeworx, distinguishing it from sibling tools. It specifies that it extracts an answer using only the tool result, giving a clear verb+resource+scope.

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

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

It provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with examples. It also gives a when-not-to-use: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, naming the 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?

The description provides exhaustive behavioral details far beyond annotations: fan-out examples per category, response shapes, resolver contract, parent event extraction, news fallback fields, safety short-circuits, wide spread handling, and resolution-rule risk. 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 very long but well-structured with clear sections (classifiers, fan-out examples, response shapes, resolver contract, etc.). While every sentence adds value, its length could be reduced for conciseness.

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

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

Given the tool's complexity and lack of output schema, the description covers all aspects: input types, processing logic, response fields, edge cases (low confidence, closed markets), and safety warnings. It leaves no ambiguity about what the tool returns.

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

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

Schema coverage is 100% and description adds context for each parameter: examples for 'market', explanation of 'depth' enum values, and the trade-offs for 'include_raw'. This adds meaningful guidance 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: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It lists accepted inputs (slug, URL, question text) and distinguishes from sibling tools like polymarket_edges by focusing on comprehensive data gathering.

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 the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' However, it does not mention when not to use it or provide alternative sibling tools.

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

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

Adds significant detail beyond annotations: describes exact data pulled for each type (revenue, net income, cash, debt for companies; adverse events, approvals, trials for drugs), sources (SEC EDGAR/XBRL, FAERS), and special handling (off-calendar fiscal years). Mentions sorting by primary metric and return format (paired data + citation URIs). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint).

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 user triggers, then clear purpose, then detailed behavior. Every sentence adds value, though slightly long. Structured logically with type-specific details.

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 all aspects: input format, data sources, sorting, output format (paired data + citation URIs), and efficiency claim (replaces 8-15 lookups). No output schema, but description explains return values adequately.

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

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

Schema coverage is 100% with enum and descriptions, but the description adds richer context: explains what each type pulls, gives concrete examples for values (tickers/CIKs for companies, names for drugs), and clarifies min/max items. Adds meaning beyond schema.

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

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

Description clearly states it does side-by-side comparisons of 2-5 companies or drugs, with specific data sources (SEC EDGAR for companies, FAERS/FDA trials for drugs). It uses natural language triggers ('X vs Y', 'compare') and differentiates from single-entity lookups like entity_profile.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and gives examples of when to use. Could be improved by mentioning when not to use, but the examples and sibling context provide sufficient 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?

The description discloses auth requirements (free sign-in, paid for thorough), timing (15-60s, up to 90s), the gaps[] and contradictions[] facets, the citation_uri fetchability guarantee, and semantic excerpting behavior. These go beyond the readOnlyHint/openWorldHint annotations and add significant operational detail.

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 each section contributes distinct operational context: prerequisites, fallback, core capability, usage guidance, iteration modes, citation semantics, and performance expectations. It is well-structured with semicolon-separated clauses, though it could be slightly tightened.

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 (no output schema), the description covers the return packet contents, gaps handling, hop fields, citation URIs, contradictions, and timing. It also addresses prerequisites and comparisons to siblings, making it a thoroughly complete description for an agent.

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

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

The schema already provides a solid description for both parameters (100% coverage). The tool description adds value by detailing the practical implications of depth (default standard, paid thorough, gap recovery and contradiction scans) and by affirming that broad/multi-part questions are acceptable for the question parameter.

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

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

The description clearly states that deep_research performs grounded multi-source research over structured data, decomposes questions into facets, and routes to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and from ask_pipeworx by positioning it for broad/multi-part questions over structured data.

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

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

It explicitly provides when-to-use guidance: best for broad/multi-part questions over structured data, and recommends ask_pipeworx for single lookups and breaking/current-news topics. It also states the account requirement and fallback for non-signed-in users.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that results are ready to call directly with no second schema lookup, enhancing transparency beyond annotations.

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

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

Description is comprehensive but not overly long; it front-loads the purpose and uses clear structure. A minor reduction in domain listing could improve conciseness.

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

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

Given no output schema, description explains that returns top-N tools with names, descriptions, schemas, examples, ready to call. Also covers usage context and aliases, making it complete.

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

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

Schema coverage is 100% with parameter descriptions. Description adds context on query aliases and limit bounds, and provides example queries (FDA drug approvals, housing market).

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 'Find tools by describing data or task' with specific verb+resource. It lists many domains (SEC filings, financials, etc.) and distinguishes itself from sibling tools as the discovery tool.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set' and describes when to use it ('browse, search, look up, discover').

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds significant behavioral detail: it fans out across multiple sources, specifies return fields, mentions patent source sunset in May 2025 with soft-fail behavior, and explains fallback for news. 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 a single, information-dense sentence that includes examples, behavior, and limitations. While not the most concise, it is well-structured with examples first and important caveats at the end. Could be slightly shorter but effectively communicates all needed info.

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

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

Given the tool's complexity (multiple data sources, fallbacks, no output schema), the description thoroughly explains what is returned (cik, company name, recent filings with URIs, fundamentals, patents, news, LEI) and covers limitations (names not supported, patent sunset). It feels complete for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by reinforcing the parameter format (ticker or zero-padded CIK), explicitly stating that names are not supported, and recommending resolve_entity for names. This goes beyond the schema's own descriptions.

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

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

The description explicitly states it provides a full cross-source profile of a US public company in one parallel call, with numerous example queries. It clearly distinguishes itself from sibling tools like compare_entities and resolve_entity by outlining its scope and limitations.

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

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

The description gives clear usage guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also notes that names are not supported and recommends using resolve_entity first, providing explicit when-to-use and when-not-to-use 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 but does not detail side effects beyond deletion. 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 wasted words. First sentence states action and resource; second provides usage guidance.

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 (one parameter, annotations present), the description is sufficient. It does not cover return values or error handling, but that is acceptable for a straightforward delete operation.

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

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

Schema coverage is 100% and the schema already documents 'Memory key to delete'. The description adds no additional parameter meaning beyond what is in 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 specifies the action 'Delete' and the resource 'memory by key', clearly distinguishing it from siblings 'remember' (store) and 'recall' (retrieve).

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

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

Provides explicit guidance on when to use: when context is stale, task done, or clearing sensitive data. Also suggests pairing 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 declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds that the tool fetches the page, extracts content, and emits markdown, providing useful behavioral context. No contradiction with annotations.

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

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

The description is two sentences, front-loaded with the main action and output, then providing usage scenarios. 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?

Given the tool's simplicity (2 parameters, no output schema, comprehensive annotations), the description covers the purpose, output format, and usage scenarios. Lacks only minor details like error handling or exact llms.txt format nuances.

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

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

Schema description coverage is 100%, and the description adds marginal value beyond schema by mentioning that the URL is fetched and summarized. Baseline 3 is appropriate as schema already documents parameters adequately.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the action, resource, and intended use for AI crawlers. It distinguishes itself from sibling tools by naming specific crawlers and the output format.

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 scenarios (client sites, own projects, auditing competitors) but does not explicitly state when not to use it or alternative sibling tools for other AI visibility tasks.

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

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

Annotations already indicate readOnly, openWorld, idempotent, and non-destructive. The description adds behavioral context: returns certified filings count, salary range, top job titles, and locations; explains legal name matching and default year behavior. No contradiction.

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

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

The description is a single paragraph with no wasted words. It front-loads the main purpose and then details returned data and parameters. Could be slightly more structured (e.g., list), but it's efficient and clear.

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 comprehensively covers inputs (employer, optional year), behavior (matching, default year), and outputs (count, salary range, top jobs, locations). No missing information for effective 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%, but the description adds value by explaining the default for 'year' (latest full year) and the matching logic for 'employer' (disclosed legal name). Examples further clarify usage. Baseline 3 plus extra context justifies 4.

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

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

The description clearly states the verb 'Check' and specific resource 'H-1B visa sponsorship' using DOL LCA data. It distinguishes from sibling tools like h1b_salary (salary focus) and h1b_top_sponsors (aggregate view) by emphasizing individual employer profiling.

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

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

Explicitly states the use case: 'Answers "does company X sponsor H-1B / green cards" for recruiting and candidate advising.' It mentions employer name matching and year filtering but does not explicitly exclude alternative tools or specify when not to use.

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

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

Annotations (readOnlyHint, idempotentHint, etc.) already convey safety; the description adds valuable context: data is from actual filings, not estimates, and returns statistics plus sample records.

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, covering purpose, data source, filtering, and output in a few clear sentences 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?

Despite no output schema, the description fully explains the return value (salary statistics + sample records), making the tool's output predictable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: job_title matched as substring, year defaults to most recent, limit default 15 max 50. This goes beyond the schema.

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

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

The description clearly states the tool looks up real H-1B base salaries from DOL LCA disclosures, distinguishing it from sibling tools like h1b_employer_sponsorship and h1b_top_sponsors.

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 answers what the tool does and provides filtering options (job title required, optional employer/city/year). It implicitly shows when to use it but lacks explicit 'when not to use' or alternatives.

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

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

Annotations already cover safety traits (readOnly, idempotent). Description adds data source ('Backed by real DOL LCA disclosures') and clarifies returns, but doesn't add major new behavioral details beyond what annotations provide.

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

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

Three sentences, front-loaded with purpose, no waste. 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?

Returns are well described (employers ranked by certified LCA filings, with filing count and median base salary). No output schema but explanation is sufficient for 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% with each parameter described. Description examples illustrate usage (e.g., uppercase city, limit max) but add minimal value beyond schema.

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

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

Description uses specific verbs ('Find which US employers sponsor'), names the resource ('top H-1B sponsors'), and gives clear query examples that distinguish it from siblings like 'h1b_employer_sponsorship' and 'h1b_salary'.

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

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

Explicitly states usage for 'candidate-sourcing / target-account signal for recruiting' and provides example queries. No explicit when-not-to-use, but sibling differentiation is clear from 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 readOnlyHint, idempotentHint, and destructiveHint. The description adds context about return fields and the include_inactive parameter, which goes beyond annotations.

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

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

Two concise sentences, front-loaded with purpose. 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?

Despite no output schema, the description lists return fields. Tool is simple with one optional parameter, and the description is fully adequate for correct usage.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema for the single parameter, which is acceptable.

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

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

The description clearly states the tool lists the caller's active subscriptions and specifies the return fields. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Provides explicit guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells when to use it and implies alternatives.

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

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

The annotations only provide generic false hints, so the description carries the burden—and it delivers: it discloses the claim_token return mechanism, the ability to later read resolution status, a rate limit of 5 per identifier per day, and that the tool is free and doesn't count against quota. 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?

Although lengthy, each sentence earns its place: core action, explicit use cases, scope exclusion, message-format guidance, token mechanism, rate limit, and cost/quota impact. The structure is front-loaded with the most important info and remains organized despite covering many operational details.

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 feedback tool with no output schema, the description is remarkably complete: it covers when to use, when not to use, how to structure the message, what the claim_token does, post-submission behavior, rate limiting, and quota impact. There are no significant gaps given the tool's relatively simple nature.

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 detailed parameter descriptions, so baseline is 3. The description adds meaning beyond the schema by instructing users to describe issues in terms of Pipeworx tools/packs rather than pasting the end-user prompt, and by demonstrating the claim_token round-trip usage. This extra guidance justifies a 4.

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

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

The opening sentence—'Tell the Pipeworx team something is broken, missing, or needs to exist'—uses a specific verb and target, precisely describing the tool's function. It clearly distinguishes this from sibling research/query tools like ask_pipeworx or deep_research, and matches the title.

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 a tool returns wrong/stale data... feature/data_gap... praise') and when not to use ('if the tool came from a different MCP server... file it with that server instead'). It also gives alternative action paths for non-Pipeworx tools and explains the claim_token workflow for later follow-up.

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 include readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: the data is self-aggregating from CF analytics-engine, no PII, and cached with windows of 5min-1h. This beyond what annotations provide.

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

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

The description is concise with three sentences, using bullet-like structure for clarity. It is front-loaded with the main result and each sentence adds value. No wasted words.

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

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

For a tool with low complexity (one optional parameter, no output schema, rich annotations), the description covers all needed aspects: what it returns, how it works, use cases, and caching behavior. No gaps remain.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the effect of window choices (shorter vs longer windows) and notes the default is 24h. This provides some additional guidance but does not significantly exceed what the schema already conveys.

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, packs, and call volume over a time window. It uses specific verbs like 'returns' and 'discovering', and the title 'Pipeworx Trending' accurately reflects the functionality. It differentiates from sibling tools like 'discover_tools' by focusing on trending data.

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

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

The description provides three explicit use cases: discovering hot data sources, confirming canonical tools, and checking alignment. It also advises on window selection (shorter for current hotness, longer for steady-state). While it doesn't explicitly say when not to use, the use cases are clear and helpful.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds valuable behavioral details: partition checks, fill checks, semantic anchor, partition filter, and response structure. 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 lengthy but well-structured and front-loaded with key usage. Every sentence adds value, but could be slightly more concise without losing information.

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

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

Given tool complexity (multiple modes, fill checks, partition checks) and no output schema, the description thoroughly explains return structure, edge cases, and references sibling tool. Complete for effective tool invocation.

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

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

Schema coverage is 100% but description adds deep meaning: explains event slug vs topic, provides examples, describes cross-event mode behavior, semantic anchor, partition filter, and fill check logic. Far exceeds schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three calling modes (no args, event, topic) with specific behavior for each, making the purpose very clear and distinct from sibling tools.

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

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

Explicit guidance on when to use each mode: no args for trending scan, event for specific market (recommended), topic for cross-event scanning. Also references polymarket_fill_risk for custom sizing, providing clear context for 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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint false, the description adds extensive behavioral context: cache policy (1h KV level), response structure with diagnostics, and details on edge computation, knobs, and segment logic. 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 well-structured with sections and bullet points, but it is verbose. Every sentence adds value, but it could be slightly more concise. It is front-loaded with the main purpose.

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

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

Given the complexity and lack of output schema, the description thoroughly explains response segments, edge metrics, diagnostics, and why segments might be empty. It is complete for the tool's scope.

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 parameters in context (e.g., tradeable-edge filters, min_partition_leg_kelly for partitions). It goes beyond the schema's type/description.

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

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

The description clearly states the tool's purpose: scanning top Polymarket markets and returning opportunities where Pipeworx data disagrees with market price, built for 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage by focusing on broad discovery across three model segments.

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

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

The description explicitly frames the tool for daily betting discovery and mentions knobs for filtering, but does not explicitly list alternatives or when not to use it. Given the sibling tools, the context implies its role.

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 the tool as readOnly and idempotent. The description adds significant behavioral details: response structure (tracked, expired, snapshot_dates), limits (60-day TTL, decay from daily closes), and snapshot gaps. 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 well-structured with clear sections (purpose, args, response, limits) and front-loaded. It is slightly verbose but every sentence adds value, so it earns its length.

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

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

Despite no output schema, the description thoroughly explains the response format (tracked[], expired[], snapshot_dates[]) and all relevant fields. It also covers limitations, making it complete for the tool's complexity.

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

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

Schema covers 100% of parameters with descriptions. The description adds default values (days=14, window='1wk'), constraints, and explains 'window' as snapshot family. This enriches understanding beyond the schema.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily polymarket_edges snapshots. It explicitly answers 'how long has this edge existed and is it shrinking?' and distinguishes itself from the sibling tool polymarket_edges by focusing on time-series trends rather than static snapshots.

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

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

The description gives a usage context with the example of fresh vs. old edges, implying when to use the tool. However, it does not explicitly name alternative tools or provide direct comparison, so some guidance is left implicit.

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

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

The description fully discloses behavioral traits beyond annotations: it explains the ladder-walking algorithm, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, etc.), and details the risks of thin books and forced directional risk. Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description aligns perfectly.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET) and every sentence adds value. It is front-loaded with the main purpose and efficiently conveys complex 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 and lack of output schema, the description is remarkably complete. It covers all return values for both modes, warns about thin legs and forced directional risk, and provides actionable context for distinguishing when to use this tool over alternatives.

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

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

Schema coverage is 100%, and the description adds significant semantic context: it explains the difference between single-market and basket modes, default values, and how size_usd is interpreted differently for buys vs sells and baskets. This goes well beyond the basic schema descriptions.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes itself from sibling tools like polymarket_arbitrage and polymarket_edges by specifying exactly when to use this tool before acting on those signals.

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

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

Explicit usage guidance is provided: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against the risk of partial fills converting an arb into a directional position, which helps the agent decide when not to rely on this tool.

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

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

The description adds extensive behavioral context beyond annotations, explaining two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and response structure. 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?

Well-structured with clear sections (modes, response, safety), but somewhat lengthy. Every sentence adds value, but it could be slightly more concise without losing information.

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

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

Given no output schema, the description comprehensively explains return values (leg-by-leg prices, matched spreads, safety fields) and covers all major aspects of the tool's behavior and limitations.

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

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

Schema coverage is 100% with descriptions, so baseline is 3. The description adds deeper semantics by explaining the two modes, how parameters interact, and the role of safety fields, exceeding the schema's descriptions.

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

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

The description clearly states the tool calculates cross-venue spreads between Kalshi and Polymarket for the same question, distinguishing it from siblings like polymarket_arbitrage. It specifies two modes and the response structure.

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

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

Provides explicit context for when to use the tool, including warnings about compatibility issues and the rarity of tradeable spreads. Does not explicitly contrast with sibling tools but sets clear expectations.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds scoping detail and listing behavior, which is useful but not essential beyond annotations.

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

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

Two sentences with no fluff. First sentence states main purpose; second adds usage advice. Perfectly front-loaded and 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?

Adequately describes tool behavior given low complexity, no output schema, and rich annotations. Could mention return format, but not essential.

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 schema already describes the parameter. Description reinforces schema without adding new semantics. 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?

Clearly states the tool retrieves a saved value or lists keys. Differentiates from sibling tools 'remember' and 'forget' by explicitly pairing with them.

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

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

Provides clear context for when to use the tool (look up previously stored context) and mentions scoping, but does not explicitly exclude alternative tools or 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 description discloses that mark_read:true mutates state, contradicting the readOnlyHint:true annotation. This is a serious inconsistency.

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. Efficient and clear.

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 all 5 optional parameters, return fields, polling suitability, and alternative access. Without output schema, description adequately informs about response contents.

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 value beyond schema: explains type as subscription type, since as ISO timestamp, and behavior of mark_read and unread_only. Schema coverage is 100%, but description enriches understanding.

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

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

Clearly states the tool pulls fired events from a subscription feed, with specific verb 'Pull' and resource. Distinguishes from siblings like list_subscriptions and subscribe by focusing on alerts.

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?

Describes when to use (polls work fine) and mentions an alternative access method (GET endpoint for scripts/dashboards). Does not explicitly compare to sibling tools but provides 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 indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description adds transparency by detailing the fan-out to multiple sources, fallback logic, and the soft-fail for USPTO patents. 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 a single paragraph that is front-loaded with example queries and well-structured. It is somewhat long but every sentence adds necessary context, balancing completeness with conciseness.

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

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

Given three parameters and no output schema, the description explains the return structure (changes grouped by source, total_changes count, citation URIs) and covers all parameters and behavioral aspects like fallback and soft-fail. It is fully adequate for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds examples for 'since' (ISO date and relative formats) and clarifies that 'type' only supports 'company'. However, this information is largely already present in the schema descriptions, so limited additional value.

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

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

The description clearly states it is a change feed for a company covering SEC filings, news, and patents. It uses specific verbs and lists sources, and distinguishes itself from the sibling tool 'entity_profile' by noting that the latter is for static profiles.

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

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

The description provides explicit example queries and explains when to use 'entity_profile' instead. It also describes fallback behavior (GDELT to GNews) but does not explicitly exclude other contexts beyond the sibling comparison.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. Description adds key details: key-value pair scoped by identifier, persistence differences (authenticated users get persistent memory, anonymous 24-hour retention). 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?

Front-loaded with primary action, then context, then scoping/persistence details. Every sentence is informative and 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?

With 2 required parameters and no output schema, description fully covers purpose, usage, behavioral nuances, and pairing with siblings. No gaps.

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

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

Schema has 100% coverage with descriptions. Description reinforces key-value pair concept and provides example key names ('subject_property'), adding marginal value beyond schema.

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

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

Description clearly states the tool saves data for reuse across conversations and sessions. It distinguishes from sibling tools like recall and forget by specifying the save action and pairing with retrieve/delete.

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

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

Explicitly describes when to use: when discovering something worth carrying forward (ticker, address, preference). Pairs with recall and forget for retrieval and deletion, setting clear 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?

The description discloses behavior well beyond the annotations: labels identifiers with sources, explicitly reports unresolved identifiers instead of omitting them, and gracefully degrades when LEI/FIGI enrichment providers are unavailable. It also notes the internal cascading of lookup endpoints, which is valuable context not captured in 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?

Although long, the description is densely packed and well-structured. It front-loads the core purpose with examples, then organizes supported types and behaviors clearly. Every sentence adds value—there is no fluff or redundancy.

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

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

With no output schema, the description carries full responsibility for explaining returns. It thoroughly covers both entity types, the identifiers returned, sources, unresolved handling, and failure degradation. This is complete enough for an agent to invoke and interpret results correctly.

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

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

Schema coverage is 100% and both parameters are already well described in the schema (enum for type, value format with examples). The description adds natural-language query examples but does not provide additional syntax or format details beyond the schema. Therefore the baseline score of 3 applies.

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

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

The description clearly states a specific verb+resource ('resolve a user-spoken NAME to the canonical/official identifiers other tools require as input') and distinguishes itself from siblings like entity_profile by focusing on identifier resolution rather than profiles. It also provides concrete examples and supported types.

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

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

Explicit guidance is given: 'Use FIRST whenever you have a name but need an ID.' It also explains that using this tool replaces 2-3 manual lookups, giving the agent a clear efficiency rationale. Supported types and input formats are spelled out, making selection straightforward.

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 false. The description adds detailed behavioral context: probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns ranked list with score, confidence, 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?

Two well-structured sentences front-load the core purpose, then provide use case and expected output. Every sentence adds value with no redundancy.

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

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

Given no output schema, the description adequately explains return values (ranked list with score, confidence, signal density per entity) and process. It covers all key aspects but could optionally detail score range or confidence calculation. Still, it is sufficiently complete for agent 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 for all 4 parameters. The description adds valuable semantics beyond schema: 'First entry treated as the "subject" for narrative; rest are competitors' and explains model options ('workers-ai free default', 'anthropic requires apiKey') and context param purpose ('disambiguates common 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 uses specific verbs and resources: 'Compare AI visibility across multiple entities side-by-side', 'probes each entity with ai_visibility_check', 'ranks by score'. It clearly distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (different comparison type).

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

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

Explicitly states the use case: 'Useful for competitive AI-marketing audits' and gives an example question. It does not explicitly list when not to use or mention alternatives, but the context is clear. Slightly missing explicit 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 indicate readOnly, idempotent, non-destructive. Description adds rich behavioral context: fans out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, and sources_failed list on timeout. Adds significant value beyond annotations.

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

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

The description is moderately long but every sentence adds value. It is front-loaded with the composite purpose and ends with graceful degradation notes. Could be slightly tighter but no redundancy.

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

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

No output schema exists, so the description fully explains return values: summary block with specific fields, per-advisory detail, links, alternative versions. It also covers edge cases like partial failures. With only 2 parameters, this is a complete specification.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds meaning: 'NPM ecosystem only in v1' (ecosystem constraint), and the version default behavior ('Defaults to the latest published version when omitted'). This extra context makes parameter semantics excellent.

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

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

The description opens with a clear composite purpose: 'Composite should I add this npm package to my project check in ONE call', specifying the exact resources (npm package) and the action (check). It distinguishes from all sibling tools, none of which are npm-related.

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

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

Explicitly states when to use: 'Use whenever an agent asks is X safe/popular/small or what does adding lodash cost me'. Also gives clear exclusion: 'NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'.

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 internal mechanics: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, a 200K char cap with truncation and flagging. This adds significant value beyond the annotations (which only indicate read-only, idempotent, open-world). The return format (offsets, similarity scores) is also described.

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: purpose first, then usage, then pairing, then technical details. It is front-loaded with the key action. However, it is slightly verbose in the technical details section; could be trimmed minimally. Still mostly 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 tool without an output schema, the description thoroughly explains what is returned (passages with offsets and scores), covers limitations (200K cap, truncation), and describes the embedding approach. Combined with 100% schema parameter coverage, this is fully complete for the 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 description coverage is 100%, providing baseline 3. The description adds examples for the query parameter and mentions the default limit but does not significantly enhance meaning beyond what the schema already provides. No additional semantic nuance is added.

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

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

The description clearly states the tool performs semantic search inside a fetched record, gives concrete examples (SEC 10-K, article), and distinguishes from siblings by mentioning pairing with ask_pipeworx_grounded. The verb 'search inside' and resource 'record' are specific and unambiguous.

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

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

The description explicitly advises use when the record is too large for the prompt, saving context. It also explains the pairing pattern with ask_pipeworx_grounded. However, it does not explicitly state when not to use or list alternative tools beyond that one, so it falls short of a 5.

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

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

Annotations indicate idempotentHint=true, but description does not clarify idempotency behavior. However, it discloses delivery channel caps (SMS 10/day), webhook auto-disable after 10 failures, and that webhook secret is returned only once. Adds good 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?

Description is fairly long but well-structured, with clear sections for type, params, and delivery. Front-loads purpose and return value. Each sentence adds value, though 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 the tool's complexity (3 params, nested objects, multiple delivery channels), description covers prerequisites, type-specific params, delivery caveats, and return value. Also references related endpoints. Highly complete.

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

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

Schema covers all parameters (100% coverage), and description enriches with concrete examples, constraints (phone verification, HTTPS requirement), and delivery channel specifics. Adds significant value beyond schema.

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

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

Description clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the new subscription id. It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by focusing on creation.

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

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

Description explicitly requires a Pipeworx OAuth account and notes anonymous/BYO cannot persist. It lists supported types with examples, but does not explicitly mention when not to use it (e.g., for one-time queries). Context is clear enough.

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

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

Annotations already disclose read-only, open-world, idempotent, and non-destructive nature. Description adds that the tool returns exact tool+argument shapes and is the onboarding entry point, which provides useful behavioral context beyond what annotations convey.

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

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

Description is appropriately sized for a meta-tool, with key phrases front-loaded in quotes. It lists example queries, describes output structure, and provides usage guidance without unnecessary words. Slightly verbose but every sentence earns its place.

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

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

Despite lacking an output schema, the description fully explains what the tool returns: category-bucketed example questions with exact tool+argument shapes. This is sufficient for an onboarding tool, leaving no ambiguity about its function.

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 already describes the optional 'topic' parameter with allowed values. Description reinforces this with examples like 'finance', 'pharma', and explains the behavioral difference: omitting gives a full spread, specifying a topic focuses results. This adds meaningful semantics.

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

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

Description uses specific verbs ('returns', 'call') and clearly states the resource: category-bucketed example questions for onboarding. It distinguishes from siblings like ask_pipeworx and discover_tools by framing it as the first step for a new agent.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also provides context for optional topic filtering and implies when not to use (if already familiar with tool capabilities).

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 discloses soft-delete behavior ('deactivated, not deleted') and ownership enforcement, adding value beyond annotations. Annotations already indicate non-destructive () and idempotent, and description aligns perfectly.

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

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

Two sentences with no redundant words. Front-loaded with the core action, then critical behavioral details. Every sentence earns its place.

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

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

The description explains the tool's effect (deactivation) and ownership constraints, sufficient for a simple tool with one parameter and no output schema. Lacks error case handling, but adequate for core functionality.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The description adds minimal additional meaning beyond the schema, so baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription by id') and resource ('subscription'), with a specific verb and object. It implicitly distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation.

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

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

The description specifies ownership enforcement ('you can only cancel your own subscriptions') and the soft-delete behavior, providing clear context for when to use the tool. However, it does not explicitly state when not to use it or compare directly to 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 mark readOnly/idempotent/non-destructive, and the description adds the crucial semantic distinction between could_not_verify, unsupported, and actual verdicts, plus the verification_error structure. It also discloses the routing behavior (financial vs non-financial) and the 'exact percent-delta math' for financial claims, which is beyond annotation info.

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 trigger phrases leading to capability, then routing details, then return semantics, then an 'IMPORTANT for callers' block. Every section adds necessary information for correct invocation and interpretation, though it could be tightened by removing some redundancy (e.g., listing both 'Is it true…' and 'true or false').

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

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

With no output schema, the description fully specifies the return value: the six verdict values, the actual value with citation, and reasoning. It also explains the two edge-case verdicts and that the tool replaces multiple sequential steps, giving the agent enough context to invoke it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful guidance for tolerance_pct: 'set 1–2 for hallucination detection' and explains the default is 'implied by wording, capped at 5.' The claim parameter is already well described with examples in the schema, and the description reinforces it with phrasing cues.

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

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

The description opens with concrete natural-language phrasings ('fact check', 'confirm or refute'), then states the resource: 'natural-language claim verification against authoritative sources.' It distinguishes itself from sibling tools by noting it replaces a 4–6 call pipeline and by specifying dual routing (SEC EDGAR vs grounded pipeline).

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 whenever the agent needs to check whether something a user said is factually correct.' It also clarifies when not to interpret results as evidence: could_not_verify means the check didn't happen, and unsupported means no source exists. This gives clear decision guidance.

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