Httpstatus

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds that the default model is free, Anthropic calls require a BYO key with direct billing, and returns per-model metrics. This provides 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?

Four sentences with zero waste. The first sentence defines the core action and output, followed by model details, return format, and use cases. Information is front-loaded and every sentence adds value.

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

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

Given the tool has 4 parameters, no output schema, but annotations present, the description adequately describes the return structure (per-model fields + combined view) and pricing. Minor gaps: no mention of entity scaling or limitations, but overall sufficient 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%, so baseline is 3. The description adds value by explaining default model behavior, the function of _apiKey ('passed straight through to api.anthropic.com'), and how 'context' disambiguates entities, which is not in 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 probes LLMs for entity knowledge and returns a visibility score (0-100) per model. It specifies the default model and optional Anthropic probe, distinguishing it from siblings like 'scan_competitor_ai_presence' by focusing on scoring visibility across models.

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

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

The description lists use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and explains when to pass an API key for Anthropic probing. However, it does not explicitly compare with siblings or state when not to use this tool.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive intent. The description adds meaningful behavioral context: it routes across 5,462 tools, returns structured answers with citation URIs, works on every tier, and is described as 'one fast call'. It does not contradict the annotations and provides extra performance and return-value 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 long but front-loaded with the most critical directive ('PREFER OVER WEB SEARCH') and packed with useful guidance. Each section contributes: domain list, routing behavior, example queries, and explicit alternatives. There is minor redundancy (e.g., 'default entry point' and 'START HERE' are repeated) that could be trimmed, but overall it is efficiently organized.

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

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

Given the complexity of the tool (routing to 5,462 sources) and no output schema, the description adequately explains the return format (structured answer with pipeworx:// citation URIs), usage domain, and alternatives. It omits details like error handling or authentication, but for a default entry point this is acceptable and still complete enough for an agent to select and invoke correctly.

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

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

The schema covers 100% of parameters, with the 'question' parameter and its aliases well-documented. The description adds examples of natural-language questions but does not substantially extend the parameter meaning; it stays at the baseline expected when the schema is already descriptive.

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 core function: routes questions to appropriate data sources and returns structured answers with stable citation URIs. It distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded, deep_research, and web search as alternatives, and by positioning itself as the default entry point.

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

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

The description gives explicit when-to-use guidance (PREFER OVER WEB SEARCH for factual questions), when-not-to-use (for hallucination-resistant single answers or broad multi-part questions), and names alternative tools by their exact sibling names. It also provides concrete examples and states that it should be the first stop for most 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context: live candidate routing tests, current equivalence to ask_pipeworx, and comparison against the stable router for merge decisions. This goes beyond the annotations without contradicting them.

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 core identity and including concrete details like the tool count and retire date. All sentences earn their place, though the date may become stale over time.

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 as a universal router and the absence of an output schema, the description covers current behavior, usage, and experimental status well. It references ask_pipeworx for response shape, which is helpful if the agent knows that sibling, but could have elaborated more on expected 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?

The input schema has 100% coverage, documenting the required 'question' parameter and all five aliases. The description adds no parameter-specific details, but the schema fully handles this, so a 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 identifies the tool as a beta version of ask_pipeworx, a universal router with the same 5,462 tools and response shape. It distinguishes itself from the stable ask_pipeworx by mentioning candidate routing improvements, making its purpose and scope explicit.

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 to use it 'exactly like ask_pipeworx when you want the newest routing' and clarifies that it is a full working router, not a fallback. It misses an explicit 'when not to use' but implies experimental use vs. the stable router.

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 (readOnly, openWorld, idempotent, non-destructive), the description adds critical behavioral traits: it costs an extra LLM call, returns evidence as verbatim quotes, and explicitly refuses with structured refusal_reason codes when the data doesn't answer. This transparency goes well beyond what annotations indicate.

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 and front-loaded with the essential concept. It flows logically: purpose, mechanics, return format, usage guidance, and trade-off. Every sentence adds valuable information with no filler, making it appropriately concise for the tool's complexity.

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

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

Given the tool's complexity, the description is exceptionally complete. It explains the exact return structure, refusal reasons, cost implication, and use cases. No output schema exists, so the description successfully carries the burden of explaining what the tool returns, which it does in detail.

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

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

Schema coverage is 100%, with all six parameters described as aliases for the same 'question' field. The description adds no additional parameter-specific information beyond what the schema already provides. Since schema handles parameter semantics fully, baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose as a hallucination-resistant answer mode for high-stakes reads, explaining the extraction process and return format. It explicitly distinguishes itself from sibling ask_pipeworx by noting 'Same routing as ask_pipeworx' but with grounded evidence extraction. This is a specific verb+resource+scope definition.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on' and lists high-stakes domains. It also gives an exclusion and alternative: 'prefer ask_pipeworx for casual lookups.' This clearly states when to use this tool vs alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds extensive behavioral details: market resolution, classification, fan-out, response shapes, resolver contract, edge cases (low confidence, closed markets, wide spreads), and resolution-rule risk. 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 lengthy but well-structured with clear sections and a front-loaded purpose. Every sentence adds necessary detail for correct tool invocation. Could be slightly more concise, but the density of information is justified by the tool's complexity.

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

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

The description covers all relevant aspects: input types, behavior, edge cases (low confidence, closed markets, wide spreads), parent events, news fields, and resolution rules. It is comprehensive for a research tool with no output schema.

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

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

Schema covers all three parameters with descriptions. The description adds context for 'depth' (quick vs thorough, default) and 'include_raw' (when to set true). This adds value beyond the schema, but schema coverage is already 100%, so baseline is 3; the 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 description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies inputs (slug, URL, question text) and typical use cases ('should I bet on X'). However, it does not explicitly distinguish this tool from siblings like 'polymarket_edges' or 'polymarket_arbitrage', which could overlap.

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 usage examples and contexts (e.g., 'Use for...') and warns about low-confidence resolutions and closed markets. However, it does not provide when-not-to-use guidance or directly compare to 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?

Annotations already indicate read-only, idempotent, non-destructive. Description adds specifics: for companies, it pulls latest 10-K metrics from SEC EDGAR/XBRL with correct fiscal-year handling; for drugs, it pulls FAERS and FDA trial counts. Also notes result sorting and citation URIs.

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, starting with example queries then detailing functionality per type. Slightly lengthy but every sentence adds value; could be more concise but remains 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?

No output schema, but description explains return format (paired data + citation URIs), covers both entity types thoroughly, addresses edge cases (off-calendar fiscal years), and explains sorting behavior.

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

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

Schema coverage is 100%, but description adds significant context: explains what each 'type' enum returns, gives examples for 'values' (tickers vs drug names), and notes max/min constraints 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?

Clearly states side-by-side comparison of 2-5 companies or drugs in one parallel call. Provides specific user query examples ('compare X and Y', 'rank these companies') and contrasts with sequential lookups.

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

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

Explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Includes example triggers and mentions sorting for 'largest/most/biggest' queries, providing clear when-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 mark read-only, open-world, idempotent, non-destructive. The description adds substantial behavioral context beyond these: account/auth prerequisites, parallel decomposition, findings packet structure (verbatim evidence, confidence, source, fetched_at, citation), gaps[] semantics, contradictions[] for standard/thorough, semantic excerpting of large records, and expected latency. This is rich, non-redundant disclosure.

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 (a single dense paragraph), but every sentence carries distinct value: account requirements, alternative routing, output details, depth semantics, caveats, and timing. It could be better structured with bullets or section breaks, but it is not verbose or redundant; it earns its length 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?

There is no output schema, so the description must explain return values; it does thoroughly (findings packet with evidence/confidence/source/fetched_at/citation, gaps[], contradictions[], hop field). It also covers prerequisites, failure modes (gaps for uncovered topics), timing, and depth behavior, making it complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meanings beyond the schema: it explains that depth='standard' re-angles unanswered gaps, depth='thorough' requires a paid plan and adds a full iterative hop, and the 'question' parameter can be broad/multi-part because decomposition is the point. This extra context elevates the score above baseline.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1419 STRUCTURED data sources... in ONE call' and distinguishes it from open-web search. It also contrasts with ask_pipeworx for single lookups, so the purpose is specific and well-differentiated from siblings.

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

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

Explicit guidance is provided: if not signed in, use ask_pipeworx; for single lookup, use ask_pipeworx; for breaking/current news, prefer ask_pipeworx; deep_research is best for broad/multi-part questions. Depth-level trade-offs and alternatives are explicitly named, satisfying the when/when-not/alternatives requirement.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds valuable behavioral details: returns top-N tools with full schemas and curated examples, each result ready to call directly. It reinforces the non-destructive nature 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 appropriately sized and front-loaded with the purpose. It lists many domains, which adds length but is helpful for scope. Every sentence adds value, though the domain list could be slightly more concise.

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

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

Given no output schema, the description adequately explains the return format (top-N tools with schemas and examples). It covers the tool's role as a discovery gateway, though it omits details like pagination or rate limits, which are not critical for this type of tool.

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

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

Schema description coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema; it mentions aliases and provides example queries but largely restates what is already in the schema properties.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and distinguishes from siblings by positioning itself as the first call for exploring available tools, not for answering a specific query.

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' and advises 'Call this FIRST when you have many tools available.' This provides clear context for when to use it, though it does not explicitly state when not to use it or name alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds details such as fanning out across multiple sources, soft-fail for patents after May 2025, and parallel execution. 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 long but well-structured, starting with examples and then detailing inclusions. Every sentence adds value, though minor tightening possible.

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 comprehensively lists all return fields (cik, company name, recent filings with URIs, fundamentals, patents, news, LEI). Also covers fallbacks and parameter restrictions.

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 context: type only supports 'company' with more coming, value accepts ticker or zero-padded CIK. This enhances understanding beyond the schema.

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

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

The description clearly states it is a 'full cross-source profile of a US public company in ONE parallel call'. It lists the data sources and return fields, and distinguishes from sibling tools like 'resolve_entity' by specifying that names are not supported.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'. Also provides negative guidance: 'names not supported (use resolve_entity first if you only have a name)'.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and stale context, but doesn't conflict. No additional behavioral traits beyond annotations needed.

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

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

Two sentences, front-loaded with primary action, followed by usage guidance. No wasted words.

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

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

Simple tool with one parameter, annotations, and no output schema. Description fully covers purpose, usage, and pairing with siblings. No further details needed.

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 100% with one parameter 'key' described as 'Memory key to delete.' Description only says 'by key,' adding no additional semantics beyond schema.

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

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

Clearly states 'Delete a previously stored memory by key.' Verb 'delete' and resource 'memory' are specific. Distinguishes from siblings 'remember' and 'recall' by pairing statement.

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 conditions: 'when context is stale, the task is done, or you want to clear sensitive data.' Pairs with sibling tools for 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 mark it as read-only, idempotent, and non-destructive. Description adds behavioral context: fetches the page, extracts title/description/links, emits markdown. 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?

Front-loaded with the core action, includes rational and examples in a single paragraph. No redundancy; could be slightly more terse but is well-organized.

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

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

Tool has no output schema, but description clearly states output is a text blob ready for placement. With 2 parameters and simple behavior, this covers all necessary context 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%, both parameters are already well-described in the schema. Description provides slight extra context ('Full URL', 'maximum number') but does not add significant new meaning beyond the schema.

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

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

Description clearly states it generates a production-ready llms.txt file for any URL, listing actions (fetches, extracts, emits) and the standard output format. Differentiates from siblings as no other tool creates llms.txt.

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

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

Explicitly lists three use cases (client site indexing, own project draft, competitor audit). Lacks negative guidance (when not to use) but is otherwise 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 declare readOnlyHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds that it requires no authentication ('keyless') and works offline, providing useful behavioral context beyond the annotations.

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

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

The description is a single sentence that conveys the tool's purpose, output, and key constraints ('Keyless, offline'). Every word is necessary and efficient.

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

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

Given the tool's simplicity, no output schema, and full annotation coverage, the description completely explains what the tool does, what it returns, and its usage context. 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% with a single parameter 'code' described as 'An HTTP status code, e.g. 404.' The description does not add further detail about the parameter's format or range, so the schema already provides sufficient meaning.

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

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

The description clearly states the tool looks up an HTTP status code (100-599) and returns its reason phrase, category, and meaning. It uses a specific verb ('Look up') and resource ('HTTP status code'), distinguishing it from the sibling list_http_statuses which lists all codes.

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 looking up a single status code, and notes it's keyless and offline. It indirectly differentiates from list_http_statuses, but does not explicitly state when to choose one over the other or provide exclusions.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds the filtering behavior but doesn't disclose pagination, ordering, or return format. With annotations covering safety, the contribution is adequate but minimal.

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

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

Single sentence, front-loaded with the core action, and zero wasted words. It efficiently communicates the purpose and optional filtering.

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 optional parameter, no output schema), the description is sufficient. It covers the core functionality and optional filter without requiring additional details.

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 includes examples and a clear description for the 'class' parameter. The tool description reiterates the filter option but adds no new semantic meaning beyond what the schema already provides.

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 HTTP status codes and specifies an optional filter by class (1-5). This verb+resource description is specific and distinguishes it from siblings like 'http_status'.

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

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

No explicit guidance on when to use this tool versus alternatives like 'http_status'. The description implies it's for browsing codes with optional filtering, but there is no mention of exclusions or when not to use it.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. Description adds context that it returns caller's subscriptions (not all) and the specific fields, enhancing beyond annotations.

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

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

Three concise sentences with no redundancy. First sentence covers purpose and output, second gives 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?

No output schema, but description lists all return fields. Covers usage context. Minor omission of 'params' structure is acceptable for a list tool.

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

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

Schema coverage is 100% with a clear description for include_inactive. Description does not add extra parameter info, but baseline 3 is appropriate.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource. Distinguishes from siblings like subscribe/unsubscribe and other list tools.

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

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

Explicitly advises using this to review monitoring before adding more subscriptions or to find an id to cancel. Could mention when not to use, but context is clear.

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

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

Annotations are all false, so the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), and human impact ('The team reads digests daily and signal directly affects roadmap'). It does not explicitly state whether the feedback is stored or how it is processed, but overall it provides valuable behavioral context beyond the annotations.

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

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

The description is longer than average, but every sentence earns its place—purpose, usage triggers, exclusion, framing advice, and operational constraints. It is front-loaded with the purpose and organized logically. Slightly verbose but not wasteful given the need for clear usage boundaries.

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 and all-false annotations, the description covers the essential contexts: what the tool does, when to use it, when not to use it, how to frame messages, rate limits, and quota impact. It fully equips an agent to decide whether to invoke this tool and how to construct a valid request.

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

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

Schema description coverage is 100%, so the schema already fully documents `type`, `context`, and `message`. The description reinforces the meaning of `type` by mentioning 'broken, missing, ... praise,' but adds no additional parameter-specific syntax or examples beyond the schema. A baseline of 3 is appropriate since the structured fields do the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly defines the tool's role as a feedback channel and distinguishes it from siblings like ask_pipeworx, deep_research, or subscribe by specifying the exact use case (reporting bugs, feature requests, data gaps, praise).

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 provided: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear exclusion criterion—do not report issues for tools from other MCP servers—and tells the user to file with that server instead. This is exemplary 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?

The description adds significant behavioral context beyond the annotations: it explains the data source ('CF analytics-engine'), guarantees no PII, describes the output structure ('pack, tool, count'), and states caching behavior ('5min-1h depending on window'). The annotations already indicate read-only and idempotent behavior, and the description fully aligns with them.

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 (three sentences) and well-structured: it leads with the core function, then lists use cases, and finally adds technical attribution and caching. Every sentence adds essential information 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 the tool's simplicity (one optional parameter, no output schema), the description is fully complete. It explains the return content, derived data source, privacy guarantees, caching, and purpose in the overall agent ecosystem. No additional context is needed.

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?

Although the schema covers 100% of the parameter with a clear description, the tool description adds value by explaining the semantic difference between window lengths: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This helps the agent choose intelligently.

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 precisely what the tool does: returns top tools, top packs, and total call volume over a recent window. The verb 'returns' and the specific resource list make the purpose unambiguous. It also distinguishes itself from sibling tools by focusing on aggregate usage trends of other AI agents, which is unique among the listed siblings.

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

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

The description explicitly lists three concrete use cases: discovering hot data sources, confirming canonical tools before asking questions, and checking alignment with typical agent needs. This provides clear guidance on when to use this tool and why it's valuable, effectively differentiating it from alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds substantial behavioral context: scan scope (top ~200 markets), partition filter (placeholder drop), fill check against live CLOB depth, semantic anchor for cross-event pairs (Jaccard ≥0.30), and the >3pp threshold for signals. 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 detailed but somewhat verbose, containing multiple paragraphs and technical specifics. While well-structured with inline headings and bullet points, it could be more concise to reduce cognitive load. For example, some internal processing details could be summarized.

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 compensates by thoroughly detailing the response structure and edge cases. It covers all main features: monotonicity checks, partition checks, fill check, filtering, and signals. Given the tool's complexity and lack of output schema, the description is remarkably complete.

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

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

Schema description coverage is 100% with both parameters described. The description adds extra meaning: explains acceptable event slug formats, distinguishes behavior modes, and describes response fields (gap_pp, suggested_trade, etc.) and special cases (skipped_low_similarity, placeholders_filtered). This goes beyond the schema's concise descriptions.

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

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

The description clearly states it finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It specifies three modes: no args for trending scan, event for specific event slug, topic for cross-event scan. This distinguishes it from sibling tools like polymarket_edges or polymarket_fill_risk.

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

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

The description explicitly instructs when to use each parameter mode, including recommendations (e.g., 'event recommended for a specific market'). It also advises against trading when realizable_edge_pp ≤ 0. However, it does not directly compare with sibling tools to guide choice between them.

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

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

The description extensively discloses behavioral traits beyond annotations: three model families with specific mathematical details, response structure (by_segment, diagnostics), caching policy (1h at KV level), and tradeable-edge filters. It aligns with annotations (readOnlyHint true, idempotent true) and adds significant context about what the tool computes.

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: purpose first, then model families, response layout, knobs. Every sentence adds value, though some redundancy exists (e.g., repeating 'edge_pp_net' components). For a complex tool, the detail is justified and not wasteful.

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 9 parameters, no output schema, and complex logic, the description is remarkably complete. It explains the response top-level fields, diagnostics, caching, and all filter behavior. The only minor gap is lack of explicit JSON example, but field descriptions compensate 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 each parameter documented. The description adds extra context for several knobs (e.g., min_kelly, slippage_pp, tradeable-edge filters) explaining their purpose and typical values, going beyond the schema alone. For example, it clarifies that min_partition_leg_kelly applies to per-leg Kelly inside partitions.

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 top Polymarket markets and returns opportunities where Pipeworx data disagrees with market price, with a specific use case 'what should I bet on today'. It distinguishes from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on discovery of mispricings without paging hundreds of markets.

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 clear use case for daily betting opportunities and mentions agents can discover opportunities without manual paging. However, it does not explicitly state when not to use this tool or directly reference sibling alternatives for different tasks (e.g., pure arbitrage vs. edge tracking).

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: history bounded by 60-day TTL, decay from daily closes not intraday, gaps mean no scan. 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?

Front-loaded with purpose and response structure. Every sentence adds value, though slightly verbose on response format. Well-organized.

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

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

Thoroughly explains return fields (tracked[], expired[], snapshot_dates[]) and caveats (history limits, gaps). No output schema, so description carries full burden and does so excellently.

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. Description restates parameter info without adding new meaning; 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 starts with precise verb ('edge persistence and decay telemetry') and resource ('daily polymarket_edges snapshots'). Answers a specific question ('how long has this edge existed and is it shrinking?'), clearly distinguishing from sibling tools like polymarket_edges which provide current edges.

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

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

Provides clear context ('a fresh wide edge and a 3-week-old wide edge are different trades') but does not explicitly state when not to use or name alternatives. Sibling tool polymarket_edges is implied as alternative.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds specifics: walks the order-book ladder, returns fields like top_of_book, vwap_fill_price, slippage_pp, and warns about forced directional risk. This expands on the annotation safety profile.

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

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

The description is verbose but well-organized with clear section headers for SINGLE-MARKET and BASKET modes. Every sentence adds value, but some redundancy (e.g., parameter defaults repeated) could be trimmed. Still effective.

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

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

Despite no output schema, the description thoroughly documents return values for both modes, including edge cases (thin_legs, forced_directional_risk, max_clean_notional_usd). It covers the full complexity of the tool's two operational modes.

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

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

Schema coverage is 100%, but description adds crucial context: explains the meaning of side defaults (auto for basket), different interpretation of size_usd per mode (spend vs target proceeds vs settlement notional), and parameter interplay (market vs event exclusive). This 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 specifies the tool's purpose as a realizable-vs-theoretical edge check against live CLOB depth. It clearly distinguishes single-market and basket modes, and explicitly contrasts with sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description states exactly when to use the tool: before acting on polymarket_arbitrage signals or polymarket_edges trades above $500. It explains the risks (uncapturable overround, unnhedged positions) and provides mode selection guidance via REQUIRES one of market or event.

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, non-destructive. The description adds critical context: explains compatibility_warning scenarios (non-equivalent bet shapes, semantically unrelated events), temporal_alignment, and skipped counting. This goes well beyond the annotations and sets accurate expectations about sparsity of tradable signals.

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 (TWO MODES, RESPONSE, SAFETY FIELDS). It front-loads the core purpose. While dense, every sentence provides meaningful information; minor redundancy in warnings could be trimmed but overall efficient.

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

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

No output schema exists, so description must cover return values. It does: leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, skipped counters. Given the tool's complexity (cross-venue matching, multiple warning fields), the description is remarkably complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by detailing the two modes, explaining the overriding behavior for explicit tickers, and listing all topic shortcuts. The examples in the schema also reinforce usage.

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 computes 'cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes itself from sibling polymarket tools by focusing on the spread across two venues, which is unique among the sibling 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 explains two explicit modes (topic shortcuts and custom tickers) and provides guidance on when spreads are meaningful (e.g., compatibility_warning cases). It lacks explicit 'when not to use' but the warning about pre-mapped topics often returning warnings implicitly advises caution.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds scoping detail ('Scoped to your identifier (anonymous IP, BYO key hash, or account ID)') and explains listing behavior. 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, each serving a distinct purpose: function, usage context, and scope/pairing. Front-loaded and no wasted words.

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

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

Completely describes behavior for a simple read tool. Explains both retrieval and listing modes, scoping, and pairing with sibling tools. No output schema needed as return values are clear.

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 description 'Memory key to retrieve (omit to list all keys)'. Description repeats this but adds no new semantic detail beyond what the schema provides.

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 'retrieve a value previously saved via remember, or list all saved keys (omit the key argument)'. Distinguishes 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 explicit context: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' Also explains when to omit the key for listing and mentions scoping. Pairs 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?

Annotation contradiction: tool is marked readOnlyHint=true yet the description details a side effect (mark_read:true flags events as read, modifying state). This contradicts the read-only hint.

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

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

Four sentences cover purpose, return fields, filtering, side effect, and alternative access, with no unnecessary detail. Information is front-loaded.

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

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

Given no output schema and optional params, the description covers key return fields, filtering, and side effect. Lacks explicit mention of default ordering or edge cases, 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%, and the description adds meaningful value beyond the schema by explaining the mark_read effect and the feed context, enhancing 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 clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', distinguishing it from sibling tools that may involve searching or other actions.

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 mentions that polling works and provides an alternative endpoint for scripts/dashboards, but does not explicitly compare to siblings like 'search_within' or state when not to use.

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

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

Discloses fan-out behavior across multiple APIs, fallback logic (GDELT to GNews on rate limits), and soft-fail for USPTO. Describes return structure (grouped changes with counts and URIs). Adds context beyond annotations.

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

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

The description is information-dense and front-loads with intuitive examples. While relatively long, every sentence contributes essential detail. Minor redundancy could be trimmed.

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 key aspects: data sources, parameter meaning, return structure, fallback behavior, and relationship to sibling tool. No output schema exists, but the description adequately explains return format.

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 existing descriptions. The description adds value by explaining relative shorthand for 'since', acceptable formats for 'value' (ticker or CIK), and that 'type' is currently limited to '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 the tool's purpose: providing a change feed for a company in a specified time window. It gives example queries and explicitly distinguishes from the sibling tool 'entity_profile' 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?

Provides explicit when-to-use guidance with example queries, explains data sources, and advises when to use the sibling 'entity_profile' instead. No ambiguity about 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 show idempotentHint=true and non-destructive. Description adds beyond annotations: scoped by identifier, persistence details (persistent for authenticated, 24h for anonymous). 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?

Concise 4 sentences. Each sentence adds value: purpose, usage, storage details, pairing. Front-loaded with core action. No unnecessary words.

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

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

For a write tool with no output schema, description covers purpose, usage, storage mechanics, pairing with siblings. Complete for agent to select and invoke correctly.

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

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

Schema coverage 100% with clear param descriptions. Description adds context: 'any text' for value, example key patterns like 'subject_property'. Enhances understanding of what to store.

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?

Explicitly states the tool saves data for reuse, with verb 'save' and resource 'data'. Clearly distinguishes from sibling tools like 'recall' and 'forget' by focusing on storing key-value pairs.

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

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

Provides explicit when-to-use guidance: 'when you discover something worth carrying forward'. Suggests pairing with recall and forget, and mentions persistence rules for different session types.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds valuable behavioral context: it returns specific fields (ticker, CIK, RxCUI, ingredient, brand), includes citation URIs, and cascades through multiple lookup endpoints internally. This goes beyond the safety profile to explain result richness and internal behavior, though it stops short of discussing edge cases or failure modes.

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 efficient. It front-loads with user-friendly query examples, then defines the core purpose, and then provides structured details for each supported type. Each sentence adds useful information, though the quotes and line breaks make it slightly less scannable than a more disciplined structure.

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

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

Given there is no output schema, the description carries the full burden of explaining return values. It does this thoroughly: for company, it lists ticker, 10-digit CIK, company_name, and citation URI; for drug, it lists RxCUI, ingredient, brand, and citation URI. It also clarifies input flexibility and internal cascading, making the tool's behavior complete and predictable 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 input schema already describes both parameters with 100% coverage, so the baseline is 3. The description adds practical semantics by giving input examples (e.g., 'AAPL', '0000320193', 'ozempic') and explaining that the tool is auto-disambiguated, which clarifies expected value formats and behavior. This extra guidance elevates the score above baseline.

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

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

The description opens with concrete example queries like "What's the ticker for…" and clearly states the verb+resource: "resolve a user-spoken NAME to the canonical/official identifier other tools require as input." It also details the two supported entity types (company, drug) and the specific identifiers returned, distinguishing it from sibling tools that focus on profiles or 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 gives an explicit usage directive: "Use FIRST whenever you have a name but need an ID." This tells the agent exactly when to invoke this tool. It also mentions that the tool replaces 2-3 manual lookups, implying it is the efficient choice for name-to-ID resolution.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds context: probes each entity with ai_visibility_check, ranks, and returns a 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 sentences, no waste. Front-loaded with the core purpose. Every phrase 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?

No output schema, but description explicitly states return format: ranked list with score, confidence, signal density per entity. Parameters fully covered by schema. Complete for a comparative analysis tool.

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

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

Schema description coverage is 100%, so parameters are already well-documented. Description adds only minor context (first entity treated as subject). Baseline 3 is appropriate.

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

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

Clearly states it compares AI visibility across multiple entities side-by-side, ranks by score, and surfaces most/least recognized. Distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (more general) by specifying the AI-presence focus.

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 'Useful for competitive AI-marketing audits' and gives an example question. Clearly indicates when to use. Could mention when not to use (e.g., single entity would use ai_visibility_check), but current guidance 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?

Annotations already declare read-only, open-world, idempotent. The description adds critical behavioral details: partial failures, bundlephobia timeout (5-30s), and the sources_failed field. No contradictions with annotations.

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

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

Single paragraph but well-organized, front-loaded with key purpose and usage. Could be slightly more concise, but each sentence adds necessary 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?

Output schema is absent, but the description thoroughly lists all return fields (summary block, per-advisory details, links, recent versions). Covers partial failure behavior, making the tool's output fully 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% with descriptions. The description adds value by noting scoped packages are accepted and default version behavior, which goes beyond schema.

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

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

Clearly defines the tool as a composite check for npm packages, covering license, security, and size. Distinguishes from siblings by specifying NPM-only in v1 and referencing deps.dev:version for other ecosystems.

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 an agent asks about safety, popularity, or size of an npm package. Also provides constraints and alternatives (non-NPM packages should use 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?

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds significant technical context: uses BGE-base-en embeddings with cosine similarity, 500-character overlapping windows, a 200K character cap with truncation, and that results include offsets and similarity scores. No contradiction with annotations; these details help the agent understand behavior beyond safety.

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

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

The description is a single paragraph of about six sentences, each serving a distinct purpose: purpose, usage scenario, technical details, pairing, and algorithm specifics. No fluff or repetition. Front-loads key 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 the moderate complexity and rich annotations/schema, the description covers input, output (passages with offsets and scores), limitations (200K cap, truncation), and pairing with a sibling. No output schema exists, but return structure is described adequately. Could mention handling of no matches, but overall complete enough for effective invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing natural-language example queries for the 'query' parameter and stating the text character cap. The 'limit' parameter's default and range are not repeated but the schema already handles that. Overall, it augments the schema meaningfully.

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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes itself from the sibling tool 'ask_pipeworx_grounded' by explaining that this tool retrieves passages while the other grounds over them. The purpose is explicit 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 says 'Use when the record is too big to cram into the prompt', providing clear guidance. It also recommends pairing with 'ask_pipeworx_grounded' for grounding. While it doesn't explicitly say when NOT to use, the guidance is strong and actionable.

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

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

Adds details beyond annotations: OAuth requirement, one-time webhook signing secret, SMS phone verification, auto-disable after 10 failures. Annotations already indicate idempotent, not read-only, not destructive; description fills in operational specifics.

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 front-loaded purpose, prerequisites, then type and delivery details. Somewhat lengthy but justified by the complexity of the tool.

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

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

Covers inputs, return value, and key behaviors. No output schema, but description gives enough for an agent to invoke correctly. Missing error or duplicate-handling info, but idempotentHint partially addresses that.

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, but description adds meaningful context for each parameter, especially concrete examples for all subscription types and operational notes for delivery (e.g., webhook HMAC, SMS cap).

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

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

Clearly states it creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. Distinguishes from sibling tools like 'unsubscribe', 'list_subscriptions', 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?

Provides prerequisites (Pipeworx OAuth account), supported types with examples, and delivery channel options. Doesn't explicitly contrast with siblings but gives clear context for when this tool is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that it returns category-bucketed example questions with tool+argument shapes, and that it's safe to call with no arguments. This adds useful behavioral context 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 user-style questions and well-structured. While slightly wordy, every sentence contributes value. It could be trimmed slightly but remains effective.

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

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

For a low-complexity discovery tool with one optional parameter and no output schema, the description fully covers when to use it, what it returns, and how to customize. 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% (one optional parameter). The description adds meaning by specifying possible topic values ('finance, pharma, economics, ...') and the behavior when omitted (full spread).

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 an onboarding entry point for discovering what Pipeworx can do, returning categorized example questions. It distinguishes from siblings like ask_pipeworx by specifying it's for initial orientation.

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 mentions optional topic filtering and provides examples of topics.

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

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

Discloses ownership enforcement and soft-delete behavior (deactivated, not deleted), adding value beyond annotations that show non-destructive and idempotent.

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 fluff, front-loaded with action and constraint.

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?

Simple tool with one required param and no output schema; description covers purpose, constraint, and behavior sufficiently.

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

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

Only one parameter with full schema coverage; description merely says 'by id' without adding extra 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?

Clear verb 'cancel' with resource 'subscription'. Distinct from siblings like subscribe and list_subscriptions.

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

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

States ownership constraint and that the row is deactivated not deleted, but does not explicitly mention when to use vs alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral traits: it replaces 4-6 sequential calls, details the two paths (structured vs. grounded), and explains the return verdicts. This provides valuable context beyond annotations.

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

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

The description is a single paragraph but is well-structured and front-loaded with examples. It efficiently conveys all necessary information without fluff. A more structured format (e.g., bullets) could improve readability slightly, but it is still concise and effective.

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

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

Despite lacking an output schema, the description fully explains the return value (verdicts, actual value with citation, and reasoning). It covers input parameters, behavior, processing paths, and output, making the tool 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%. The description explains the claim parameter with examples and the tolerance_pct parameter with default behavior and usage guidance, adding meaning beyond the schema definitions.

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

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

The description clearly states the tool's purpose: verifying natural-language claims against authoritative sources. It provides example user intents ('Is it true that...', 'fact check') and distinguishes between company-financial claims and other claims, making the purpose explicit and distinct from siblings.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct.' It explains the two processing paths (SEC EDGAR for financial claims, grounded pipeline for others). While it doesn't explicitly say when not to use, the guidance is clear enough for an AI agent to decide.

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