Buzzword Density

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral details: returns per-model {score, confidence, signals, raw_response} plus combined view, and explains cost implications for Anthropic calls. No contradictions.

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

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

The description is concise with three well-structured sentences, front-loaded with the main purpose and key details. 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?

For a tool with 4 parameters and no output schema, the description is quite complete: it covers default model, optional parameters, return structure, and use cases. It could mention pagination or limits, but overall adequate.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the purpose of `_apiKey` (passed straight through to Anthropic) and `context` (disambiguation), which exceeds the schema descriptions.

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

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

The description clearly states the verb 'probe one or more LLMs' and the resource 'business / brand / product / topic', and distinguishes from sibling tools like ask_pipeworx or bet_research by focusing on visibility scoring. It is specific and unique.

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 guidance on when to probe (AI-marketing audits, pre-launch brand checks, competitive monitoring) and which model to use (default free, Anthropic with key). It lacks explicit when-not-to-use but is clear enough for the agent.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. The description adds that it routes questions to 3,745 tools, fills arguments automatically, and returns citations. It does not contradict annotations and provides behavioral details beyond them, though no mention of latency or limits.

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 most important usage advice, followed by examples. It is somewhat lengthy but every sentence adds value; could trim redundant phrasing but overall well-structured.

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

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

For a complex tool with no output schema, the description covers purpose, usage, internal routing, and citations. It lists many domains and example queries. Could detail the response format more, but sufficient given the breadth.

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 aliases documented. The description adds value by specifying that the parameter accepts natural language questions and gives example queries, surpassing the schema's minimal 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 that this tool handles factual queries using authoritative structured data, listing many domains. It specifies the verb 'ask' and resource 'Pipeworx'. However, it does not distinguish itself from the sibling 'ask_pipeworx_grounded', missing the top-level differentiation.

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

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

Explicitly advises 'PREFER OVER WEB SEARCH' for many query types, provides concrete examples, and gives trigger words ('what is', 'look up', etc.). It sets clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral detail: return format with answer, evidence, confidence, source, fetched_at, and explicit refusal reasons (e.g., not_in_source, no_tool_match). This goes well 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?

Description is front-loaded with purpose and usage guidelines, but slightly verbose with details about routing and refusal reasons. Could be more concise, but every sentence adds value.

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

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

Despite no output schema, the description fully specifies the return format and all possible refusal reasons. It also explains the internal mechanism (routing across 3,745 tools) and the cost trade-off. Context is complete for high-stakes use cases.

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

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

Schema coverage is 100% with all 6 properties described. The description explains that q, text, input, query, prompt are aliases for question, which adds clarity beyond the schema. No other parameter semantics needed beyond the natural language question.

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 as a 'hallucination-resistant answer mode for high-stakes reads,' specifying the verb 'ask' and resource 'Pipeworx Grounded.' It distinguishes from the sibling 'ask_pipeworx' by highlighting the grounded mode's refusal reasons and extra cost.

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

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

Explicitly advises when to use the tool ('when an answer will be quoted, cited, or acted on') and when not ('prefer ask_pipeworx for casual lookups'), citing the extra LLM call cost. Provides clear alternatives and 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe read operation. The description goes far beyond this, detailing resolution logic, classifier fan-out, response shapes, safety mechanisms (low-confidence matches, closed markets, wide spreads), resolution-rule risk, and even practical pitfalls from audited arb-bot ledgers. 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 thorough but verbose, spanning multiple paragraphs with extensive detail. While it is structured with sections (classifiers, fan-out examples, response shapes, safety), it could be more concise. Every sentence contains useful information, but the length may challenge quick parsing by an AI agent.

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 input types, classifier fan-out, detailed response structure, edge cases), the description is remarkably complete. It explains return fields (result.market, result.analysis, result.evidence), resolver contract, parent event extractor, news fields, safety mechanisms, and resolution-rule risk. No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100%, but the description adds substantial value beyond the schema. It explains the three input formats for 'market', enumerates examples for 'depth' (quick vs. thorough), and provides rationale for 'include_raw' (default false to keep responses small, true for full payloads). This context helps the agent choose appropriate parameter values.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies the exact input formats (slug, URL, question text) and what the tool returns (evidence packet, market-vs-model comparison). This differentiates it from sibling tools like polymarket_edges or polymarket_arbitrage, which focus on different aspects of betting.

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

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

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear usage scenarios. It also explains the fan-out behavior and categories, but does not explicitly state when not to use this tool or mention alternatives beyond the sibling context.

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

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

Annotations already declare the tool as non-destructive, read-only, and idempotent. The description enhances this by specifying the exact return values (count, density, severity, flagged terms) and the optional roast mode, providing complete behavioral clarity.

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

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

The description is extremely concise at three sentences, front-loading the core purpose and listing outputs without any filler or repetition.

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

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

The description adequately covers the inputs and outputs for a tool of low complexity, and the presence of an output schema (implied) further reduces the need for more detail. The annotations also provide strong context.

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

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

All three parameters have descriptions in the schema (100% coverage), so the description adds minimal extra value. It does mention 'roast_mode' contextually but does not go 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 states a specific verb ('analyze') and resource ('text for overused industry jargon'), clearly distinguishing it from sibling tools like 'validate_claim' or 'scan_dependency'. It also lists explicit outputs, leaving no ambiguity.

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

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

The description implies usage for analyzing text with jargon, and mentions an optional 'roast_mode' feature. However, it does not explicitly state when not to use or compare to alternatives, though the unique purpose makes this less critical.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. Description adds value by detailing data sources (SEC EDGAR for companies, FAERS for drugs), fiscal year handling, sorting by primary metric, and return format (paired data + URIs). Some behavioral traits like rate limits or edge cases are not mentioned, but overall good context.

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

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

The description is packed with useful information but is somewhat lengthy. It is front-loaded with examples and key guidance. Could be slightly more concise, but every sentence serves a purpose and adds value. 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 the complexity of the tool (multiple entity types, data sources, sorting, return format), the description covers all essential aspects: entity types, what data is retrieved, how results are sorted, and the output includes citations. No output schema exists, but the description sufficiently explains return format. Complements schema and annotations fully.

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. Description adds meaning beyond schema by specifying what data each type pulls (e.g., '10-K revenue + net income + cash + long-term debt' for company, 'adverse-event counts, FDA approval counts, active trial counts' for drug) and clarifying values format (tickers/CIKs vs names). This enhances the agent's understanding of parameter 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?

The description uses specific verbs (compare, rank, head to head) and clearly states it performs side-by-side comparison of 2–5 companies or drugs. It distinguishes from siblings like entity_profile which likely handles single entities.

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

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

Explicit guidance to ALWAYS PREFER this tool over sequential single-pack lookups when comparing entities. Provides natural language triggers and examples. Does not state when not to use, but the preference is clear and context is sufficient.

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

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

Adds significant behavioral context beyond annotations: gaps are explicit (never invented), requires Pipeworx account, depth 'thorough' requires paid plan, expected 15-60s, returns structured findings packet. No contradictions with annotations.

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

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

Description is slightly long but front-loaded with key benefit. Every sentence adds value: purpose, mechanism, usage, requirements, timing. Could be trimmed but effective given complexity.

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

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

No output schema, but description explains return format thoroughly: 'verbatim evidence, confidence, source, fetched_at, citation, gaps array'. Also covers prerequisites and timing. Very complete for a complex tool.

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

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

Schema coverage is 100% (baseline 3). Description adds value by explaining the depth enum values (quick=3, standard=5, thorough=8 paid) and clarifying that the question can be broad/multi-part. Adds meaning beyond schema.

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

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

The description states it's 'Grounded multi-source research in ONE call' and explains how it decomposes questions and routes to many tools. It distinguishes from sibling ask_pipeworx by specifying use for broad/multi-part questions. Clear verb and resource.

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 ('broad or multi-part questions') and when not to ('use ask_pipeworx for single lookups'). Mentions account requirements and depth level restrictions. Provides complete usage guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds valuable behavioral details: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas... each result is ready to call directly.' 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 purpose and usage, and ends with a call to action. It is efficient but somewhat lengthy due to the enumerated domains. Every sentence adds value, but 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 complexity (6 parameters with aliases), full schema coverage, and lack of output schema, the description sufficiently explains the tool's behavior, return content, and usage context. It covers all necessary information for an agent to decide when and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds the list of specific domains (SEC filings, FDA, etc.) that help inform parameter values, but the aliases and examples are already well-covered in the schema. However, the domain list provides additional context for crafting queries, justifying a score of 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 'Find tools by describing the data or task' and specifies the tool's purpose as a discovery tool. It distinguishes from siblings by advising 'Call this FIRST when you have many tools available and want to see the option set.'

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

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

The description explicitly says 'Use when you need to browse, search, look up, or discover what tools exist for' followed by a list of domains, and advises 'Call this FIRST... not just one answer.' This provides clear usage guidance and 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 readOnly, openWorld, idempotent, and non-destructive. The description adds significant behavioral context: it fans out across multiple sources, returns specific fields (cik, company_name, recent_filings with URIs, fundamentals sorted by period_end, patents with a soft-fail note about USPTO sunset, news via GDELT→GNews fallback, LEI). This transparency about what the tool does and how it handles failures 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?

The description is a single dense paragraph that packs examples, usage guidance, data sources, return fields, and failure handling into one flow. It front-loads the purpose with query examples. While it could be broken into bullet points for easier parsing, it remains concise without wasted words. Loses a point for density but still efficient.

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

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

Given the tool's complexity (multiple sources, no output schema, 2 required parameters), the description is remarkably complete. It details all return values: CIK, company name, filings with URIs, fundamentals with sorting, patents with sunset warning, news with fallback chain, and LEI. Combined with annotations that cover safety, the agent has all necessary context to invoke and understand the output.

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%: both parameters are described in the schema. The description repeats the same information for 'type' ('Only company supported today; person/place coming soon') and 'value' ('Ticker or zero-padded CIK'). It does not add new semantic meaning beyond what the schema provides. Baseline score of 3 is appropriate since the description adds no extra value here.

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 multiple example queries ('Tell me about X', 'research Acme', 'brief me on Tesla') that immediately convey the tool's purpose: providing a holistic profile of a US public company. It explicitly states 'full cross-source profile' and lists the data sources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It also distinguishes itself from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups', making it clear what this tool does uniquely.

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

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

The description gives explicit guidance: 'ALWAYS PREFER over chaining single-pack... when the user asks for a holistic view.' It also specifies input constraints: 'Pass ticker "AAPL" or zero-padded CIK "0000320193" — names not supported (use resolve_entity first if you only have a name).' This clearly tells the agent when to use this tool (holistic profile) and when to use an alternative (resolve_entity for names).

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false. Description adds context about clearing sensitive data, which is helpful beyond annotations. 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: first defines action, second provides usage guidance. No unnecessary words. Efficient and front-loaded.

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

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

Given simple tool with one parameter, annotations, and no output schema, the description covers all necessary context for an agent to use it correctly.

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

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

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

Description states 'Delete a previously stored memory by key' with a specific verb (delete) and resource (memory). It distinguishes from siblings like 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with 'remember' and 'recall', providing clear context and exclusions.

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

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

The description details behavioral traits beyond annotations: it fetches the page, extracts title/description/links, and outputs standard markdown. This adds context about external fetch and processing steps that annotations (readOnlyHint, idempotentHint) do not cover.

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

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

The description is three sentences, front-loaded with the main verb and resource, and each sentence adds value without redundancy. No wasted words.

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

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

Given the tool's simplicity (2 params, no output schema) and rich annotations (readOnlyHint, idempotentHint), the description provides all necessary context: purpose, behavior, usage, and output format. It is fully complete for an AI agent to select and invoke correctly.

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

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

The schema already describes both parameters with 100% coverage. The description adds extra meaning: default and max for max_links ('default 25, max 50') and clarifies url as 'Full URL of the site to summarize', which enriches the schema's description.

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

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

The description clearly states the tool generates a production-ready llms.txt file, specifying the action (generate), resource (llms.txt for any URL), and output format. It distinguishes itself from siblings by its unique purpose of creating llms.txt files for AI crawler indexing.

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

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

The description provides explicit use cases such as getting a client's site indexed, drafting for own projects, or auditing competitors. However, it lacks any 'when not to use' guidance or explicit comparisons to sibling tools, which prevents a score of 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds value by detailing specific return fields and suggesting typical workflow, which helps agent understand safe read behavior.

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

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

Two concise sentences with no fluff. Every word adds value.

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

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

For a simple list tool with one optional param and no output schema, the description provides complete context: return fields, single parameter implication, and use case.

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 parameter description is clear. Description does not add extra info about the 'include_inactive' parameter, 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?

Description uses specific verb 'list' and resource 'the caller's active subscriptions', clearly distinguishing from siblings like 'subscribe' and 'unsubscribe'. It also mentions specific return fields, adding precision.

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

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

Explicitly says when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for usage, though does not explicitly mention alternatives.

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

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

The description discloses behavioral traits beyond annotations: rate-limited to 5 per identifier per day, free (no quota), and that the team reads digests daily affecting roadmap. No contradiction with annotations.

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

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

The description is concise and well-structured, front-loading purpose and including all necessary usage details without unnecessary words.

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

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

The description provides sufficient context for a simple feedback tool, including what happens after submission (digests, roadmap impact). Could mention response behavior 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?

The input schema has 100% description coverage, and the description adds context beyond schema (e.g., how to frame feedback). The enum for type is clearly explained.

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 sends feedback to the Pipeworx team, listing specific categories (bug, feature, data_gap, praise). It distinguishes from sibling tools, which are all about information retrieval or analysis.

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

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

The description explicitly says when to use the tool (bug, missing tool, praise) and provides guidance on how to describe issues (in terms of Pipeworx tools/packs, not user prompts). It also mentions rate limits and that it's free.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds data sourcing (CF analytics-engine, no PII, just counts) and caching (5min-1h), which is beyond annotations. No contradictions.

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

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

Three sentences, front-loaded with purpose, then use cases, then technical details. Every sentence adds value; 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?

Complete for a simple tool with one optional parameter, no output schema. Covers input options, use cases, data source, privacy, caching. No missing info.

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% with enum and description for window. Description adds semantic meaning: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This goes beyond schema.

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

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

The description clearly states the tool returns top tools, packs, and call volume for a recency window. It uses specific verb 'returns' and resource 'trending data', distinguishing it from siblings like ask_pipeworx or discover_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 use cases are given (discovering hot data sources, confirming canonical tools, aligning use case). The window parameter's effect is explained: shorter windows for hot trends, longer for steady-state. No ambiguity.

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

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

The description goes beyond annotations by detailing internal logic (semantic anchor, partition filter, fill check) and output structure (opportunities array, partition_check, fill_check). It also explains conditions like the placeholder fraction threshold and when signal should not be traded. 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 comprehensive but verbose, with many details that could be condensed. It is front-loaded with the critical requirement, but the length may hinder quick scanning. Adequate for the complexity but not optimally 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 and lack of output schema, the description covers output format, conditions for signals, and the fill check. It lacks error handling details for invalid inputs and data freshness info, but is largely complete for an agent to use effectively.

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

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

With 100% schema coverage, baseline is 3. The description adds substantial value by explaining each parameter's purpose, giving example values, and noting that full URLs are accepted. It clarifies the difference between event and topic modes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies two modes (event and topic) and distinguishes itself from sibling tools by focusing on arbitrage, not edge tracking or fill risk.

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

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

The description explicitly requires one of `event` or `topic` and recommends when to use each mode. It also directs to a sibling tool for custom sizing ('For custom sizing use polymarket_fill_risk'). However, it does not explicitly state when not to use this tool versus other Polymarket siblings.

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

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

Exceeds annotation requirements by detailing caching (1h KV-level), model families, edge calculation (including slippage and Kelly fractions), and diagnostic output. No contradiction with annotations (readOnlyHint, idempotentHint, etc.) is present.

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

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

The description is thorough but verbose, including detailed model explanations that may not be necessary for tool selection. It is front-loaded with purpose but could be more concise by summarizing model details or relegating them to external docs.

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 9 parameters and no output schema, the description is exceptionally complete. It explains output structure (by_segment, diagnostics), caching, filter effects, and edge cases (Fed bets, stale data), giving an agent full confidence in using the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining parameter interactions and usage context, such as the function of 'min_partition_leg_kelly' for partition arbs and how 'slippage_pp' affects edge calculation.

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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. It uses specific verbs ('scan', 'return') and resources, and distinguishes itself from siblings like 'polymarket_arbitrage' by focusing on edge detection from Pipeworx data and providing unique 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 states it is built for 'what should I bet on today' and explains the three opportunity segments and adjustable knobs. While it provides clear context for when to use, it does not explicitly mention when not to use it or compare with 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description explains response structure, snapshot creation on cache miss, gaps meaning no scan, and decay computation. No contradictions.

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

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

The description is somewhat lengthy (~500 chars) but well-structured: purpose first, then response fields, then limits. Every sentence adds value, but some could be 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?

With no output schema, the description provides a detailed response format (tracked[], expired[], snapshot_dates[]) and covers limits and interpretation, making it complete for the tool's purpose.

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

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

Schema coverage is 100%, and the description adds little beyond the schema: it mentions default values and clamping but these are already in schema descriptions. 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 it provides edge persistence and decay telemetry from daily snapshots, answering how long an edge has existed and whether it's shrinking. It distinguishes itself from siblings like polymarket_edges by focusing on time-series analysis.

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

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

The tool's use case is implied by contrasting fresh edges with old ones, and limits are provided (60-day TTL, decay from daily closes). It doesn't explicitly state when not to use it or name alternatives, but the context is clear.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and not destructive. Description adds significant behavioral detail: explains returns for each mode (verdict, capture ratio, thin legs, forced directional risk) and clarifies that partial fills can strand an arb unhedged. 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 long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). It is front-loaded with the core purpose and required parameters. However, it could be slightly more concise without losing essential details given the complexity.

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

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

No output schema is provided, so the description must explain return values. It does so thoroughly for both modes: lists specific fields (top_of_book, vwap_fill_price, slippage_pp, etc., for single-market; theoretical_sum, realizable_sum, capture_ratio, thin_legs, forced_directional_risk for basket). Covers risks and edge cases. Complete for the tool's complexity.

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

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

Schema has 100% description coverage. Description adds context beyond schema: explains size_usd as 'settlement notional' in basket mode, default side logic ('auto from partition sum'), and interprets defaults (e.g., size_usd default 1000). Adds meaning to parameters.

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

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

The description clearly states the tool checks 'realizable-vs-theoretical edge against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It links to sibling tools by specifying when to use this tool before polymarket_arbitrage or polymarket_edges, making the purpose unambiguous.

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

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

Explicitly advises 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains the risk of partial basket fills converting arb into directional position, providing clear when-to-use and why.

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

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

Annotations already declare read-only, open-world, and idempotent behavior. The description adds significant behavioral context beyond annotations, including the two modes, response structure, safety fields (compatibility_warning, temporal_alignment), and counters. Contradiction flag is false.

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

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

The description is verbose and includes detailed explanation of safety fields and counters. While front-loaded and structured, some sentences could be condensed without losing meaning. It is not as concise as it could be.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly explains return values (leg-by-leg prices, spread, safety fields) and edge cases (compatibility_warning, temporal_alignment). It covers all necessary aspects for correct invocation and interpretation.

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 3 parameters. The description adds meaning by explaining the purpose of each parameter, the two modes, and that explicit tickers override topic. It also clarifies the topic shortcuts list, adding 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?

The description clearly states the tool computes the spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs 'cross-venue spread' and distinguishes it from sibling tools like polymarket_arbitrage and polymarket_edges by focusing on same-question comparison.

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

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

The description explicitly lists two modes (topic shortcuts and explicit tickers) and provides guidance on when to use each. It also warns that pre-mapped topics may not always be tradeable, guiding interpretation. However, it does not explicitly state when not to use the tool or list alternatives, though the sibling context implies this.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context: scoping to identifier and behavior when key is omitted (list all keys). No contradictions.

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

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

Two sentences, no wasted words. First sentence states primary action, second provides usage context and pairing. Front-loaded and efficient.

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

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

Given no output schema, the description does not specify the return format, but the purpose is clear. It covers scoping, pairing, and use cases. Minor gap in explicit output description.

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 semantic meaning by explaining that omitting the key lists all keys, which is not explicit in the schema 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 retrieves a saved value or lists all keys, specifying the verb 'Retrieve' and 'list' and the resource 'value previously saved via remember' and 'saved keys'. It distinguishes from siblings 'remember' and 'forget'.

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

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

The description explains when to use the tool: to look up context stored earlier without re-deriving it, and it scopes the retrieval. It implicitly suggests not using it for saving or deleting, but does not explicitly list alternatives beyond mentioning remember/forget.

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. Description adds behavioral details: returns source, citation_uri, raw payload; explains mark_read behavior affects next call; confirms polling is fine. No contradictions.

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

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

Description is four sentences, each adding essential info: purpose, return fields, filters, mark_read behavior, and alternative endpoint. No wasted words; front-loaded with key 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?

Despite no output schema, description explains return fields. All parameters covered in schema and description. Annotations provide safety profile. Sibling tools are not conflicting. Description is sufficient for an agent to use correctly.

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

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

Schema coverage is 100% with descriptions for all 5 params. Description adds value by giving an example for type (sec_8k), clarifying mark_read effect (flags read so next call shows newer ones), and mentioning limit defaults. Exceeds baseline of 3.

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

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

Description clearly states the tool pulls fired events from subscription feed and returns recent alerts with specific fields. Differentiates from siblings like list_subscriptions which lists subscriptions, not 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?

Description provides clear context: says polling works fine and mentions an HTTP alternative for scripts/dashboards. Does not explicitly exclude other tools but gives enough guidance on when to use this vs. the direct endpoint.

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, etc. The description adds detailed behavioral context: fans out to multiple sources, fallback logic (GDELT→GNews), soft-fail for USPTO, and return structure (grouped sources, total_changes, citation URIs). 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 well-structured paragraph, front-loaded with clear examples, then explains sources and behavior. Every sentence provides useful information without verbosity.

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

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

Given no output schema, the description explains the return format (changes grouped by source, total_changes, citation URIs), covers all parameter behaviors, sources, fallback, and failure modes. It also links to the alternative tool 'entity_profile'.

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 'since' parameter accepts ISO dates or relative shorthand, provides examples like '7d', '30d', '3m', '1y', and recommends '30d' for monitoring. Also clarifies 'value' can be ticker or CIK, and 'type' is only 'company'.

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's a change feed for a company in the last N days/weeks/months, with examples of queries like 'What's new with X'. It distinguishes from the sibling tool 'entity_profile' by explicitly telling when to use that instead.

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

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

Provides explicit usage examples, recommends typical values for the 'since' parameter (e.g., '30d' or '1m'), and tells when NOT to use this tool (use entity_profile for static profiles).

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 idempotentHint=true, and description adds key behavioral traits: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. 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?

Concise three sentences: purpose, usage guidelines, then additional context. No wasted words, front-loaded with core function.

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

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

No output schema, but description covers purpose, usage, behavior, and persistence. Minor gap: doesn't mention return value (likely success/failure). However, given tool simplicity, it is mostly complete.

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

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

Schema coverage is 100% with descriptions for key and value. Description does not add new parameter details beyond 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?

Description clearly states the verb 'Save data' and resource 'data the agent will need to reuse later', and distinguishes from sibling tools recall and forget by 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?

Explicitly says when to use: 'when you discover something worth carrying forward', and provides alternatives: 'Pair with recall to retrieve later, forget to delete.'

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

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

Annotations already declare readOnly and idempotent. Description adds that each call cascades through several lookup endpoints, replacing manual steps. No contradictions. Adds useful context beyond annotations.

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

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

Description is well-structured: starts with examples, then usage guidance, then type-specific details. Every sentence adds value, no waste.

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 two-entity-type resolver with no output schema, the description fully explains return formats, inputs, and internal behavior. Covers all relevant aspects.

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

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

Schema coverage is 100%, but description adds significant detail: for each type, explains return values (ticker+CIK for company; RxCUI for drug) and acceptable input formats. Goes well beyond 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 resolves names to identifiers with specific verb and resource. It distinguishes from siblings by focusing on identifier lookup, not profiles or comparisons.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Provides clear context for when to use, though no explicit when-not-to or alternative tools listed.

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

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

All annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false) are consistent. The description adds detailed behavioral context: probes each entity with ai_visibility_check, ranks by score, returns ranked list with score/confidence/signal density per entity. No contradictions.

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

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

The description is concise (3 sentences) and well-structured: front-loaded main action, then details, then use case, then return format. Every sentence adds value without redundancy.

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

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

Despite no output schema, the description fully explains the return value ('ranked list with score, confidence, signal density per entity'). It covers all parameters, usage context, and behavioral traits, making it self-contained for agent 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 covers 100% of parameters, so baseline is 3. The description adds meaning beyond schema: explains that the first entity in 'entities' is treated as the subject for narrative, that 'models' defaults to workers-ai, and that '_apiKey' is only needed if 'anthropic' is in models. This enriches agent understanding.

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

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

The description clearly states 'Compare AI visibility across multiple entities side-by-side' and specifies that it probes entities with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from the sibling tool ai_visibility_check, which likely handles single entities.

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

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

The description provides explicit context: 'Useful for competitive AI-marketing audits' and an example question. It implies when to use (comparing multiple entities) and notes the first entity as subject. Lacks explicit when-not-to-use or direct alternative mentions, but the sibling list provides implicit differentiation.

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

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

Annotations already provide readOnly, idempotent, and non-destructive hints. The description adds significant behavioral detail: composite nature, partial failure handling, potential 5-30s delay on bundlephobia first measurement, and the graceful degradation with sources_failed. 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 relatively long but every sentence is informative. It front-loads the main purpose and then details behavior and return format. Could be slightly streamlined, but justified given tool complexity.

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

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

Despite no output schema, the description fully explains the return format (summary block with specific fields, per-advisory detail, links, alternatives) and behavior on partial failures. This is complete for an agent to understand tool capabilities.

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 mentioning scoped packages (e.g., '@types/node') and defaulting version to latest when omitted, which are not in schema descriptions but are useful clarifications.

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 as a composite check for npm packages, combining data from deps.dev and bundlephobia. It explicitly answers 'should I add this npm package' and distinguishes from sibling tools by being specific to npm ecosystem analysis.

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

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

The description explicitly states when to use it ('when an agent asks is X safe / popular / small'), provides alternatives for other ecosystems (PyPI, Maven, etc.), and warns about potential delays with bundlephobia. This fully guides usage decisions.

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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds key behavioral details: embedding model BGE-base-en, 500-char overlapping windows, cosine similarity, 200K char cap with truncation and flagging. This goes beyond annotations and fully discloses the internal workings.

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

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

The description is a single, front-loaded paragraph of four sentences. Each sentence earns its place: purpose, usage, benefits, and technical specs. No redundancy or wasted words.

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

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

Given no output schema, the description explains the return format (passages with character offsets and similarity scores). It covers input, output, pairing with a sibling tool, and technical limitations (200K cap). The agent has all needed context to use and verify 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 description coverage is 100%, but the description adds value beyond schema: it specifies the 200K char limit for text, the range 1-20 for limit with default 5, and example queries for query. This enriches the schema without repeating it.

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

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

The description clearly states the tool performs 'semantic search INSIDE a fetched record' and provides concrete examples (SEC 10-K, article). It distinguishes from sibling ask_pipeworx_grounded by contrasting 'fetch with the gateway, ground over the relevant passages', which sets the tool's unique role.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded as a complementary workflow. It implies when to use but does not list alternatives or when-not conditions, though the context is clear.

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

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

The description contradicts the annotation idempotentHint=true. The description implies each call creates a new subscription (non-idempotent), while the annotation claims idempotency. This is a serious inconsistency that misleads the agent about the tool's behavior.

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

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

The description is dense but well-organized, with clear sections for types and delivery methods. Every sentence adds value, and the structure is readable.

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 subscription tool with multiple types and delivery options, the description covers prerequisites, rate limits (SMS cap), error conditions (webhook auto-disable), and verification steps. No output schema is needed; the description states the return value.

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 extensive meaning: explains each type value, provides concrete examples, clarifies optional vs required fields, and details delivery channel constraints (phone verification, SMS cap, webhook auto-disable). This goes well beyond the schema.

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

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

The description clearly states the tool creates a proactive monitoring subscription and returns a new subscription ID. It distinguishes from siblings like list_subscriptions and unsubscribe by specifying it creates subscriptions. The types and delivery channels are well defined.

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

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

The description explains when to use it (to set up monitoring) and prerequisites (Pipeworx OAuth account, phone verification for SMS). It does not explicitly state when not to use it or list alternatives, but the context is sufficient for an agent to decide.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds that it returns example questions and tool shapes, which is consistent and provides useful 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?

Well-structured and front-loaded with alternative phrasings. A few extra words, but generally concise for the amount of context provided.

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

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

Complete given the tool's simplicity (one optional parameter, no output schema). Covers purpose, usage, parameter, and when to use. With strong annotations, no gaps.

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

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

Schema coverage is 100% with one parameter 'topic'. Description adds that omitting gives cross-category spread and lists example topic values, adding meaning beyond schema's description.

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

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

The description clearly states the tool is the onboarding entry point, returning category-bucketed example questions with tool+argument shapes. It lists categories and optional topic parameter, effectively distinguishing it from siblings like ask_pipeworx.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' Also describes usage with no arguments vs. topic filter.

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 non-destructive behavior, but the description adds crucial details: ownership enforcement, deactivation instead of deletion, and linkage to 'recent_alerts' for historical events. This goes beyond annotation information.

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 the main action, each sentence adds essential information: action, ownership, and deactivation behavior. No redundant text.

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

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

The description fully explains the tool's behavior for a simple single-parameter operation, including ownership and deactivation, and mentions where historical events remain accessible. This is sufficient given the tool's simplicity and sibling tools.

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

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

Schema coverage is 100%, and the schema already describes the 'id' parameter as 'Subscription id (uuid) returned by subscribe.' The description does not add new information about the parameter, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Cancel a subscription by id', specifying the verb 'cancel' and resource 'subscription'. It differentiates from 'subscribe' (creation) and 'list_subscriptions' (listing) through its action and additional details on ownership and deactivation.

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 ownership enforcement ('you can only cancel your own subscriptions') and explains the deactivation behavior, implying when to use. However, it lacks explicit alternatives or conditions for not using this tool, such as when permanent deletion might be needed.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about the output format (verdict, structured form, citation, percent delta) and mentions that it replaces 4-6 sequential calls, enhancing transparency without contradiction.

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

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

The description is front-loaded with example phrases, then states the use case, constraints, and output. It is slightly verbose but every sentence conveys necessary 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 single parameter, rich annotations, and no output schema, the description is fully complete. It covers the domain, usage context, output details, and how it improves efficiency over sequential calls.

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

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

With 100% schema description coverage and a single parameter 'claim', the schema already explains the parameter. The description adds examples ('Apple's FY2024 revenue was $400 billion') but does not significantly extend beyond the schema's own 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: verifying natural-language claims against authoritative sources, specifically company-financial claims for public US companies. It uses clear verbs like 'validate', 'check', 'verify' and distinguishes from siblings by emphasizing that it replaces multiple sequential calls, unlike other tools in the list.

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

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

The description explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and specifies the scope (company-financial claims). While it does not list when NOT to use it, the domain is clear, and the sibling list provides alternatives for other tasks.

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