Ocrspace

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral context: default model (Workers AI Llama-3.3-70b free), BYO key for Anthropic with direct payment, and return format (per-model score, confidence, signals, raw_response). 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?

Three sentences, each providing essential information: action and output, model usage and payment, and return structure. No redundant or extraneous content.

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

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

Given 4 parameters and no output schema, the description adequately explains the return structure (per-model object + combined view) and clarifies the optional API key usage. Could mention that output schema is missing but not critical.

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 parameters described. The description adds meaning: explains default model behavior, API key purpose for Anthropic, and context parameter for disambiguation.

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 verb 'probe', the resource 'LLMs', and the output 'score visibility (0-100)'. It clearly distinguishes from siblings like 'ask_pipeworx' by focusing on visibility scoring rather than direct Q&A.

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 when to use the tool: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. It implicitly distinguishes from siblings but does not explicitly mention when not to use or name specific 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, and openWorldHint. The description adds valuable behavioral context: it routes to one of 5,529 tools across 1,455 sources, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is a 'one fast call' default. It does not mention rate limits or error handling, but the added context goes beyond 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 longer than typical but every sentence serves a purpose: usage priority, source scope, citation behavior, examples, alternatives, and default status. It is front-loaded with the key instruction ('PREFER OVER WEB SEARCH') and the structure flows logically from what to do, to when to use, to when to step up. Though not as terse as a two-sentence ideal, the content density justifies its length.

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

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

For a broad, generic question-answering tool with no output schema, the description covers all necessary context: what sources it draws from, what the return includes (structured answer with citations), when to use it, when to escalate, and example queries. An agent can confidently invoke this tool without needing additional clarifying information.

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

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

Schema coverage is 100%: all six parameters are aliases for 'question' and each is described in the schema. The description adds minimal additional parameter semantics, merely stating the question should be in natural language. Since the schema already documents aliases and the required field, the description adds little beyond confirming natural language input, meeting the baseline but not exceeding it.

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

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

The description clearly states the tool's purpose: answering factual questions about real-world entities/events/numbers by routing to one of 5,529 tools across verified sources, returning structured answers with citation URIs. It explicitly distinguishes itself from web search and sibling tools like ask_pipeworx_grounded and deep_research, with specific examples of use cases.

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

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

Provides explicit when-to-use guidance ('PREFER OVER WEB SEARCH'), trigger phrases, concrete examples, and when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant single answer, deep_research for broad/multi-part questions). Also clarifies it's the default entry point and works on every tier, making usage boundaries clear.

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

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

The description adds valuable context beyond the annotations: it explains the beta status, that no candidate is currently active, that it matches ask_pipeworx exactly right now, and that it is a fully working router. This goes beyond the readOnly/idempotent hints and clarifies the current operational state.

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

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

The description is four sentences, each providing meaningful context about the beta nature, current state, and usage. It is slightly wordy (repeating 'identical' and 'same') but generally efficient and well-structured.

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

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

For a beta tool with no output schema, the description covers the essential context: what the tool is, its current operational state, how to use it, and what happens with results. It could mention the response shape in more detail, but overall it is complete enough for an agent to select and invoke it.

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

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

The schema provides 100% coverage with all parameters documented as aliases for 'question'. The description only mentions 'same arguments' without adding specific parameter details, so it falls to the baseline for well-covered schemas.

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

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

The description clearly states this is a beta version of the ask_pipeworx universal router, with the same 5,529 tools and arguments. It distinguishes itself from the stable ask_pipeworx and the grounded variant by highlighting its experimental nature and live candidate routing improvements.

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

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

Explicit guidance is given: 'Use it exactly like ask_pipeworx when you want the newest routing' and notes it currently matches ask_pipeworx exactly since no candidate is active. This clearly indicates when to use this tool versus the stable 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 signal read-only and idempotent, but the description adds critical behavioral disclosures: the tool extracts answers ONLY from tool results, returns explicit refusal_reason codes, and costs one extra LLM call. These are not apparent from annotations alone.

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 compact and front-loaded, but slightly dense with multiple clauses and examples in the refusal list. It is well-structured and each sentence contributes, though a few examples could be trimmed without losing 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 no output schema, the description fully explains return values, refusal reasons, and the exact scenarios for use. It is complete for a tool with complex behavior, covering both success and refusal paths.

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 aliases documented. The description does not add any parameter-specific semantics beyond what the schema already provides. Baseline of 3 is appropriate since the schema carries the full burden.

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 is a hallucination-resistant answer mode for high-stakes reads, with a specific verb ('extracts the answer') and resource (ask_pipeworx routing). It explicitly distinguishes itself from its sibling ask_pipeworx by noting it extracts grounded answers and refuses when data doesn't directly answer.

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: 'Use whenever an answer will be quoted, cited, or acted on...' and even names the alternative for casual use: 'prefer ask_pipeworx for casual lookups.' Also notes the extra LLM call as a trade-off.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds extensive behavioral context: safety mechanisms (low-confidence short-circuits), closed market handling, wide-spread warnings, resolution-rule risk, and fallback logic for news sources. No contradictions with annotations.

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

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

The description is very long and dense, with structured sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.). While thorough, it could be more concise; some details (e.g., fan-out examples) are extensive. Front-loaded with purpose and usage, but overall length impacts conciseness.

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

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

Given 3 parameters, no output schema, and complex behavior, the description is extremely thorough. It covers response shapes, resolver contract, parent event extraction, news fallback, safety edge cases, and cancellation rules. An agent has all needed context to understand outputs and limitations.

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

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

Schema covers all 3 parameters with descriptions (100% coverage). The description adds value by explaining market input formats (slug, URL, question text), depth default, and the meaning of include_raw beyond the schema's summary. However, it repeats some schema info.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from siblings (e.g., ask_pipeworx, deep_research) by focusing on Polymarket bets and mentioning classifiers and fan-out patterns unique to this tool.

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

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

Explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This provides clear context and implies alternatives (siblings like ask_pipeworx for general queries). No when-not-to-use is needed given the specificity.

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

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

Beyond annotations (readOnly, openWorld, idempotent), the description adds behavioral traits: handles off-calendar fiscal years, sorts results by primary metric, returns citation URIs, and specifies data sources per type (SEC EDGAR/XBRL for companies, FAERS/FDA for drugs).

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 front-loading the purpose with example triggers, then details data behavior and limitations. Every sentence adds value; no wasted words.

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

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

For a tool with two parameters and no output schema, the description adequately explains inputs and outputs conceptually. Could specify output format more precisely, but given the tool's purpose, it's sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining what data each type retrieves and providing examples for values. This enhances the schema definitions without redundancy.

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

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

The description uses specific verbs and resources: 'compare', 'side-by-side comparison of 2–5 companies or drugs'. It clearly distinguishes from sibling tools like 'entity_profile' (single entity) and 'ask_pipeworx' (general Q&A) by stating it replaces sequential lookups and handling specific data sources.

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 to prefer this tool over sequential single-pack lookups for comparisons. Provides example queries and contexts. Does not list specific alternatives by name, but the guidance is strong.

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 destructiveHint=false, but the description adds substantial behavioral context: returns findings with evidence, confidence, source, fetched_at, citations, gaps[], contradictions[], hop fields, excerpting semantics, and latency expectations. It also discloses account/auth requirements and that citations are only returned when fetchable. 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 dense and long, but every sentence adds value—covering auth, use cases, behaviors, limitations, and parameters. It is not front-loaded with the core purpose (starts with account requirements), and the single-block format hurts scannability. Minor deduction for length and structure, yet it remains efficiently packed.

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 high complexity (5,529 tools, depth tiers, citations, gaps), the description is exceptionally complete. It explains return packet structure, gap/contradiction handling, latency expectations, excerpting behavior, and when results will be empty. No output schema exists, so the description fully carries the burden of explaining outputs and edge cases.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes far beyond schema descriptions. It elaborates on depth values: quick=3 facets, standard=5 with gap recovery and contradictions, thorough=8 with iterative lead-chasing and paid. It also clarifies the question parameter accepts broad/multi-part natural language, adding meaningful semantics not present in the schema.

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

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

The description clearly identifies deep_research as a grounded multi-source research tool over Pipeworx's 1455 structured data sources, decomposing questions into facets and routing them in parallel. It explicitly distinguishes itself from siblings like ask_pipeworx ('For a single lookup use ask_pipeworx') and clarifies it is NOT open-web search. The verb 'research' plus specific resource scoping makes purpose unambiguous.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and contrasts with ask_pipeworx for single lookups and breaking/current-news topics. Also gives account prerequisites and a fallback ('If you are not signed in, use ask_pipeworx instead'). Alternatives are named directly with reasoning.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds that it returns top-N tools with full schemas and curated examples, ready to call directly. No contradictions.

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

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

Single paragraph, front-loaded with purpose. Information-dense but not overly long. Could be slightly more concise but remains clear.

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

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

No output schema, but description fully explains return content (top-N tools, names, descriptions, full schemas with examples). Simple one-param tool; covers all needed context.

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

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

Schema coverage is 100%, so baseline is 3. Description adds little beyond schema (e.g., mentions aliases already in schema). The examples of queries are helpful but schema already documents 'query' as natural language.

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 'Find tools by describing the data or task' and lists many example domains (SEC filings, FDA drugs, etc.). Distinguishes from sibling tools by positioning itself as the first call when many tools exist.

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

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

Explicitly says 'Use when you need to browse, search, look up, or discover what tools exist' and 'Call this FIRST when you have many tools available'. Provides clear context for when 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?

Adds context beyond annotations: fans out across multiple sources, describes return fields, notes USPTO API sunset and soft-fail behavior, and fallback mechanisms. No contradiction with annotations.

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

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

Description is somewhat lengthy but all sentences add value. Front-loaded with trigger phrases. Minor redundancy could be trimmed, but generally 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 only 2 parameters and no output schema, description comprehensively explains return fields (cik, filings, fundamentals, patents, news, LEI) and behavior (parallel fan-out, soft-fails). Complete for the tool's complexity.

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

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

Schema coverage is 100%, but description adds meaning: explains that 'value' accepts ticker or zero-padded CIK, 'type' is limited to 'company', and clarifies names are not supported.

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

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

Description clearly states it provides a 'full cross-source profile of a US public company in ONE parallel call', listing specific sources and distinguishing from sibling tools like resolve_entity for names.

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 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' for holistic views, and specifies that names are not supported, directing to resolve_entity. Provides example inputs.

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

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

Annotations already declare the tool as readOnly, idempotent, and non-destructive. Description adds minimal behavioral context, only noting the output is 'recognized text'. No mention of file size limits, supported formats, or processing time, which limits transparency beyond annotations.

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

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

Two sentences, zero waste. The first sentence states core function and input/output; the second adds use cases and an engine recommendation. Essential 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?

For a tool with 5 parameters, 1 required, and no output schema, the description covers purpose, use cases, and default engine. It could elaborate on the output format (e.g., plain text) or limitations, but is otherwise sufficient 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 description coverage is 100%, so the baseline is 3. The description does not add new parameter details beyond the schema's own descriptions. It simply echoes the engine recommendation without clarifying format or constraints.

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 extracts text from images/PDFs via OCR using a URL. Verb 'extract' and resource 'text from image/PDF' are specific. No sibling tool performs similar OCR, so it is well-distinguished.

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

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

Description lists concrete use cases (screenshots, scanned documents, receipts, signs) and recommends Engine 2 for most cases. It lacks explicit when-not-to-use guidance but the sibling list contains no competing OCR tools, so this is adequate.

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

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

Description aligns with annotations (destructiveHint=true, idempotentHint=true) and adds context about clearing sensitive data. However, it does not elaborate on permanence or side effects beyond what annotations convey.

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

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

Two concise sentences with no wasted words. First sentence captures purpose, second adds usage guidance. Well-structured.

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

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

Given the tool's simplicity (1 required param, no output schema), the description covers purpose, usage, and pairing with siblings completely.

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

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

Schema coverage is 100% and the schema already describes the 'key' parameter. The description adds minimal extra meaning by referencing 'by key' and providing an example.

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

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

Description states 'Delete a previously stored memory by key' with a clear verb and resource. It distinguishes from siblings 'remember' and 'recall' by mentioning pairing.

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 provides three use cases: stale context, task completion, clearing sensitive data. Mentions pairing with siblings but does not give explicit exclusions or alternatives for when not to use.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds that it fetches the page, extracts content, and emits markdown, providing granular process details that align with annotations.

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

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

The description is a single, efficient paragraph that front-loads the purpose and then covers process and use cases without any unnecessary words. Every sentence adds value.

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

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

Given no output schema and simple tool, the description covers purpose, process, output format (text blob), and use cases. It lacks error handling details but is sufficient for the tool's simplicity and read-only nature.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description does not add significant extra meaning beyond the schema; it only mentions 'any URL' and 'production-ready' but no additional parameter details.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, specifying the verb (generate) and resource (llms.txt file). It distinguishes itself from siblings by focusing specifically on llms.txt generation, not general AI visibility.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own projects, auditing competitors. While it doesn't explicitly say when not to use, the context 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.

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds return field details and the include_inactive parameter, but no additional behavioral traits beyond what annotations convey.

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

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

Two sentences with no wasted words: first states purpose and return fields, second provides usage guidance. Front-loaded and efficient.

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

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

Simple tool with one optional parameter and no output schema. Description covers purpose, return fields, and usage entirely. Annotations cover safety. Complete for the 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% and the single boolean parameter is well-described in the schema. Description does not add new parameter insights.

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 lists the caller's active subscriptions, specifies returned fields (id, type, etc.), and is distinct from sibling tools like subscribe/unsubscribe.

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

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

Explicitly states when to use: to review monitoring before adding more or to find an id to cancel. This guides the agent on appropriate 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 are all false (no positive hints), so the description carries the burden. It discloses rate limits ('Rate-limited to 5 per identifier per day'), free usage, the claim_token return mechanism, and the fact that the team reads digests daily. No annotation contradiction; the description makes the tool's side effects clear enough for an agent.

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

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

The description is long but well-structured, starting with purpose and then moving into usage, exclusions, and follow-up. Every sentence provides meaningful information, though the roadmap comment ('signal directly affects roadmap') is somewhat motivational and could be trimmed. It remains appropriately sized 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?

The description is comprehensive for a feedback tool, covering what it does, when to use it, exclusions, return behavior (claim_token), and follow-up usage. Since there is no output schema, it explains the return value well. Minor omissions like whether feedback is anonymous or tied to an account are not critical for an agent to invoke the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by instructing users to 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' which clarifies the message parameter. It also provides a concrete claim_token usage example, enhancing the schema's description.

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

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

The description states a specific verb-resource pair ('Send Pipeworx Feedback') and clearly explains it's for reporting broken, missing, or desired functionality. It also distinguishes from sibling tools by explicitly limiting scope to the current Pipeworx connection, so an agent can tell it apart from other feedback mechanisms.

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: '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 gives when-not-to-use: 'if the tool came from a different MCP server... file it with that server instead,' including a disambiguation rule ('Not sure? Pipeworx tool names are the ones this connection lists').

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. Description adds valuable details: derived from CF analytics-engine, no PII, caching (5min-1h). This goes beyond schema. Minor: could mention rate limits or data retention.

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 well-structured sentences plus a bullet list. Front-loaded with core output. Every sentence adds value. Slightly verbose with bullet enumeration, but still efficient.

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

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

Given low complexity (1 param, no output schema), the description fully covers purpose, usage, parameter guidance, and behavioral traits. No gaps remain for an agent to misinterpret.

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 (window) with 100% schema coverage. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This significantly aids agent in choosing correct value.

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

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

The description explicitly states the tool returns 'top tools, top packs, and total call volume' with specific time windows. This clearly identifies the resource and action, and the context signals show it is distinct from 40+ sibling tools.

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

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

Three concrete use cases are listed (discovering hot data sources, confirming canonical tool, checking alignment). This provides clear context for when to use. Missing explicit when-not scenarios, but the positive guidance is strong.

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

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

Beyond annotations (readOnlyHint, etc.), the description details internal logic like Jaccard similarity filtering, partition placeholder filtering, and the fill check against live CLOB depth. This gives the agent full behavioral understanding.

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 every sentence adds value, front-loading the purpose and mode selection, then diving into technical details. No fluff or repetition.

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

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

Without an output schema, the description fully explains the response structure (opportunities[] with fields, partition_check details, fill_check output). It also covers edge cases like low similarity rejection and placeholder filtering.

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 descriptions are complete (100% coverage), and the tool description adds semantic context, including accepted formats for event slugs/URLs and how the topic parameter triggers cross-event search with examples.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket using monotonicity violations and partition-sum checks. It distinguishes itself from sibling tools like polymarket_edges or polymarket_edge_tracker by specifying its unique arbitrage detection approach.

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 explains when to use each mode: no args for trending scan, 'event' for a specific market, and 'topic' for cross-event scanning. It also provides guidance on avoiding trades when the fill check shows no realizable edge.

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 significant behavioral context: caching at KV level (1h keyed on all knobs), Fed bet unreliability without paid data, diagnostics for empty segments, and a 24h move warning. 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 information-dense and front-loaded with the purpose. While lengthy, every sentence contributes value given the tool's complexity. Minor redundancy could be trimmed, but overall well-structured.

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

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

Despite no output schema, the description thoroughly explains the response structure (by_segment segments, fed_candidates, diagnostics) and edge metrics. It covers caching, limitations, and knob effects, making the tool's behavior 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%, so the schema already provides parameter descriptions. The tool description adds general context about 'tradeable-edge knobs' but does not significantly enhance parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price'. It is built for a specific user query ('what should I bet on today'), and the detailed explanation of segments distinguishes it from sibling tools like polymarket_arbitrage.

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

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

The description provides clear context for when to use the tool (agents discovering opportunities without paging hundreds of markets) and explains adjustable 'knobs' for tradeable-edge filtering. However, it does not explicitly mention when not to use it or compare it to siblings like polymarket_arbitrage.

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

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

Annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds valuable context: data comes from daily snapshots, gaps exist when no scan occurred, decay is computed from daily closes (not intraday), and history is bounded by a 60-day TTL. This enriches the behavioral model beyond the structured hints.

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

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

The description is a single dense paragraph that mixes purpose, arguments, response structure, and limits. While it is informative and front-loaded with purpose, it could be more concise and structured (e.g., using bullet points). It earns its content but sacrifices brevity.

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 bears full responsibility for explaining the response. It thoroughly details the three response arrays (tracked, expired, snapshot_dates) with field meanings, trend values, and edge cases like gaps and the 60-day TTL. This provides complete context for an agent to correctly interpret the output.

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

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

The input schema already has 100% coverage with clear descriptions for both parameters (days, window) including defaults and valid values. The description restates these but adds no new semantic information. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry' that answers 'how long has this edge existed and is it shrinking?'. It specifies the resource (polymarket_edges snapshots) and the verb (tracking persistence and decay), effectively distinguishing it from sibling tools like polymarket_edges (which likely provides current data) and others.

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 lacks explicit guidance on when to use this tool versus alternatives. It does not mention when not to use it or provide comparisons to sibling tools such as polymarket_edges or polymarket_arbitrage. The usage is implied by the purpose but not stated.

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

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

Annotations declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe read operation. Description adds critical behavioral detail about order book depth checks, partial fill risks, and the dominant loss mode (unhedged positions), going 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 dense but well-structured: starts with purpose, then mode details, then usage guidance and warnings. Every sentence is informative, though slightly long. Could be slightly more concise but all content is relevant.

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?

Comprehensively covers both modes, return fields, risk factors, and usage context. No output schema, but description details all returned metrics and warnings. Given tool complexity (two modes, risk of partial fills), the description is fully adequate.

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

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

Schema description coverage is 100%, and the description further clarifies parameter usage: e.g., REQUIRES one of `market` or `event`, explains side default behavior per mode (auto for basket), and size_usd interpretation differences between single-market and basket. Adds significant value beyond schema.

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

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

The description clearly states it's a 'Realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It details what each mode returns and explicitly references sibling tools (polymarket_arbitrage, polymarket_edges) to differentiate when this tool should be used.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also warns about partial basket fills converting an arb into unhedged directional position, providing clear when-to-use and risk 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?

Beyond annotations (readOnly, idempotent), the description discloses detailed behavior: two operational modes, response structure with leg-by-leg prices and spreads, safety fields like compatibility_warning and temporal_alignment, and counters for skipped comparisons. It also pre-emptively warns that pre-mapped topics often yield non-tradeable spreads.

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: starts with purpose, then lists modes, describes response, and details safety fields. Every sentence adds value. Slight redundancy in explaining the pre-mapped warning, but overall efficient for the complexity.

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

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

Given no output schema, the description fully compensates by detailing response fields (leg prices, spreads, compatibility_warning, temporal_alignment, counters). It covers edge cases (temporal mismatch, non-equivalent bet shapes) and sets proper expectations. The explanation is self-contained and sufficiently complete for an agent to 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 input schema already describes each parameter (topic, kalshi_event_ticker, polymarket_event_slug) with examples and descriptions. The description adds context by listing the 10 topic shortcuts, explaining that explicit tickers override topic mapping, and clarifying auto-fetch behavior. This adds moderate extra 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 computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verbs and resources ('cross-venue spread', 'Kalshi-Polymarket'), distinguishing it from intra-venue tools like polymarket_arbitrage.

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

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

The description explains the two modes (topic shortcuts and explicit tickers) and details conditions that make spreads meaningless (temporal misalignment, non-equivalent bet shapes). It warns that most pre-mapped topics are not tradeable, but does not explicitly compare to sibling tools or state when to use 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=true and destructiveHint=false. The description adds value by explaining scoping (anonymous IP, BYO key hash, account ID) and the behavior of listing all keys when omitted. No contradictions with annotations.

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

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

The description is concise, with three well-structured sentences. The main action is front-loaded, and each sentence adds clear value: what it does, when to use it, and how it relates to siblings. No unnecessary words.

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

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

Given the tool's simplicity (1 optional param, no output schema, complete annotations), the description covers all necessary aspects: operation, scoping, and relationship to related tools. It is fully sufficient 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% with a single optional parameter that has a description. The description enhances understanding by explaining that omitting the key lists all keys and providing examples of typical usage (e.g., 'user_research_topic'). This adds 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?

The description clearly states the tool retrieves a value saved via 'remember' or lists all keys when no key is provided. It specifies the resource (saved memory) and the action (retrieve/list), and distinguishes itself from sibling tools like 'remember' and 'forget'.

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

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

The description provides explicit guidance on when to use the tool—to look up stored context like target ticker or address—and mentions pairing with 'remember' and 'forget'. However, it does not explicitly state when not to use it (e.g., if fresh data is needed), which would strengthen 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 states that setting mark_read:true will flag returned events as read, modifying state. However, annotations declare readOnlyHint: true, which implies no state modification. This direct contradiction scores 1.

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

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

The description is four sentences, front-loaded with the main action, and each sentence adds critical information without redundancy. Very concise and well-structured.

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

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

Without an output schema, the description adequately explains what each alert carries (source, citation_uri, payload) and the effect of mark_read. It also mentions the alternative REST endpoint, providing sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving an example of type filter ('sec_8k'), clarifying that since is an ISO timestamp, and explaining the effect of mark_read. This exceeds the schema alone.

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

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

The description clearly states 'Pull fired events from your subscription feed' and specifies that it returns the most recent alerts with source, citation_uri, and raw payload. This distinguishes it from siblings like 'list_subscriptions' which lists subscriptions, not alerts.

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

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

The description provides clear context: it's for pulling fired events, can filter by type and since, and can mark events as read. It mentions that polling is fine and gives an alternative REST endpoint for scripts, but does not explicitly exclude 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?

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral detail: it fans out to SEC EDGAR, GDELT→GNews fallback (with conditions), and USPTO (soft-fail). It also describes the return structure (changes[] grouped by source + total_changes + pipeworx:// URIs). No contradiction.

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

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

The description is a single dense paragraph that packs many details. It is front-loaded with query examples and ends with the sibling comparison. While efficient, it could benefit from slight restructuring for readability. Still, every sentence adds value.

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

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

Despite no output schema, the description explains the return format. All three parameters are adequately described. The tool's multi-source behavior is fully explained, including fallback and failure modes. The sibling comparison is present. The description is complete given the tool's complexity.

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

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

Schema coverage is 100% and each parameter has a description. However, the description adds extra context for `since` (accepts ISO date or relative shorthand like '7d', '30d', '3m', '1y') and `value` (ticker or zero-padded CIK), and clarifies that `type` is limited to 'company'. This enriches the schema.

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

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

The description clearly states the tool provides a change feed for a company over a time window, using multiple data sources. It includes concrete query examples ('What's new with X', 'latest on Y') and distinguishes itself from the sibling tool 'entity_profile'.

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

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

The description provides explicit usage examples and context, such as 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This directly tells the agent when to use this tool versus an alternative.

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

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

Adds behavioral context beyond annotations: mentions persistence duration (24 hours for anonymous, permanent for authenticated) and scoping by identifier. No contradiction with annotations (idempotentHint=true is consistent with overwriting by key).

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 concise sentences, starting with the core purpose. Every sentence adds value without redundancy. Front-loaded with actionable 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?

Covers purpose, usage, persistence, and pairing. No output schema is provided, but the description doesn't need to explain return values for a write operation. Slight gap: doesn't mention that storing duplicate keys overwrites, but this is implied by idempotent.

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

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

Schema already provides 100% coverage with descriptions for both parameters. The description adds meaningful examples of key-value usage (e.g., 'subject_property', 'target_ticker'), adding value beyond the schema.

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

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

The description clearly states 'Save data the agent will need to reuse later' with specific examples (e.g., resolved ticker, target address). It distinguishes from siblings like 'recall' and 'forget' by mentioning them explicitly.

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

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

Provides explicit guidance on when to use: 'when you discover something worth carrying forward'. Also explains scope (by identifier), persistence differences for authenticated vs anonymous users, and pairs with recall and forget.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds substantial behavioral context: graceful degradation of LEI/FIGI enrichment when upstream sources fail, explicit listing of unresolved identifiers under `unresolved`, cascading internal lookups, and source labeling for each identifier. These details go well beyond the annotations and help the agent anticipate edge cases.

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

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

The description is longer than average but well-structured: it opens with practical query examples, states the core purpose, then details supported types and special behaviors. Every sentence carries informational weight, though some redundancy with the schema exists. It is not minimal, but 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 tool's complexity (two entity types, multiple upstream sources, graceful degradation, unresolved handling) and the absence of an output schema, the description does a strong job explaining what will be returned (identifiers, sources, unresolved array). It lacks an explicit return format or error behavior, but covers the essential context well enough for an agent to select and invoke it correctly.

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

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

The input schema already has full 100% coverage for both parameters, including accepted formats (e.g., 'ticker (AAPL), CIK (0000320193), or name') and type-specific examples. The description largely repeats this information without adding new parameter-level semantics. With high schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with specific examples (ticker, CIK, LEI, RxCUI) and an explicit directive: 'Use FIRST whenever you have a name but need an ID.' It distinguishes itself from sibling tools by focusing on identifier lookup, not entity profiles or comparisons.

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

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

The description gives explicit when-to-use guidance: 'Use FIRST whenever you have a name but need an ID.' It also implies what it replaces ('replaces 2-3 manual lookups') and supports two entity types. However, it does not mention when not to use it or explicitly compare to alternatives like entity_profile, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds behavioral context: it probes each entity with ai_visibility_check, ranks by score, 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?

The description is three concise sentences: front-loaded with purpose, then an example use case, then output description. No fluff.

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

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

No output schema exists, but the description compensates by naming the return fields (score, confidence, signal density). It also describes internal call to ai_visibility_check. Adequate for a 4-parameter tool.

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

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

Schema has 100% coverage with descriptions. The description adds meaning beyond the schema by explaining the first entity is the 'subject' and rest are competitors, and provides model examples (workers-ai, anthropic).

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

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

The description clearly states the action ('Compare AI visibility across multiple entities side-by-side') and the specific verb ('Probes each entity with ai_visibility_check, ranks by score'). It distinguishes from sibling tool ai_visibility_check by emphasizing multi-entity comparison and ranking.

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

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

The description explicitly states when to use ('Useful for competitive AI-marketing audits') and provides an example question. It does not explicitly state when not to use, but the sibling list includes ai_visibility_check, implying the single-entity alternative.

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

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

The description adds significant behavioral context beyond annotations: it fans out across two services, degrades gracefully on partial failures, notes that bundlephobia's first measurement can take 5-30s and lists which fields will indicate failure. 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 efficient, with each sentence serving a clear purpose: composite definition, usage guidance, output summary, and failure behavior. It is well front-loaded but slightly lengthy; still well-structured with no redundant content.

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

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

For a tool with no output schema, the description thoroughly explains the return value structure (summary block, per-advisory details, links, recent versions) and error handling. Combined with good annotations, it provides complete context.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds context about scoped packages and default version behavior but does not provide additional semantics beyond what the schema already conveys.

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

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

The description clearly states the composite purpose of checking an npm package for safety, popularity, and size by calling deps.dev and bundlephobia. It specifies the output structure and distinguishes from siblings by noting ecosystem limitations and alternatives.

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

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

The description explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and provides when-not-to-use guidance by stating 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare it safe (readOnly, non-destructive, idempotent). The description adds technical details beyond annotations: embedding model, window size, truncation cap, and return of offsets. 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 three sentences plus technical constraints, all front-loaded. Every sentence contributes purpose, benefit, companion tool, or implementation detail. No redundancy.

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

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

No output schema exists, but the description adequately explains return format (passages with offsets and similarity scores) and addresses edge cases (truncation flagged). It covers the key aspects needed for an agent to use the tool effectively.

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

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

Schema coverage is 100% with descriptions. The description adds value by providing example queries and clarifying usage (e.g., 'pass the text you already pulled'). This context aids the agent 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 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from sibling tools by explicitly pairing with ask_pipeworx_grounded and explaining the benefit of saving context.

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

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

The description explains when to use (record too big for prompt) and how to use (pass fetched text and query). It also mentions a companion tool (ask_pipeworx_grounded). However, it does not explicitly state when not to use or list alternatives, though the context is clear.

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

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

The description adds behavioral context beyond annotations: it details return value (new subscription id), delivery channel limitations (SMS 10/day, webhook auto-disabled after 10 failures), and account requirements. Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true), which the description supports. No contradiction.

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

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

The description is well-structured and appropriately sized. It front-loads the core purpose and return value, then systematically explains subscription types, delivery channels, and constraints. Every sentence carries useful information without redundancy or fluff.

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

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

Despite lacking an output schema, the description tells the AI what to expect (new subscription id). It covers all required parameters, optional delivery options, and important constraints (OAuth requirement, phone verification, rate limits). The tool's behavior is fully specified for correct invocation.

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

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

Schema coverage is 100%, but the description enriches parameter meaning with examples and explanations (e.g., sec_8k item codes, fred_series series_id, delivery channel details). It adds value beyond the schema's brief descriptions, helping the agent understand how to construct type-specific params objects.

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: 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It distinguishes from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and specifies the resource (subscriptions) and action (create).

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

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

The description provides explicit context on when to use the tool (creating subscriptions) and includes prerequisites: 'Requires a Pipeworx OAuth account (anonymous + BYO cannot persist subscriptions).' It also notes constraints like SMS delivery caps and phone verification. However, it does not explicitly state when not to use it or mention alternatives.

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

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

Annotations already indicate idempotent, read-only, non-destructive behavior. The description adds clarity on return structure (category-bucketed examples with tool shapes) and invocation patterns (no args vs topic filter), which is valuable beyond annotations.

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

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

The description is moderately long but well-structured with triggers, usage, and outcome. Every sentence adds value, though some redundancy exists (e.g., listing categories twice). Front-loaded with purpose.

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

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

Given the simple parameter (1 optional, no enums, no output schema) and rich annotations, the description covers all essential aspects: purpose, usage patterns, trigger phrases, and expected output. No gaps identified.

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

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

Schema has 100% coverage with a single optional 'topic' parameter. The description enriches it by listing valid focus areas and explaining that omitting it returns a cross-category spread, which adds meaning beyond the schema's type/description.

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

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

The description clearly states it returns category-bucketed example questions with tool+argument shapes, positioning it as the onboarding entry point. It distinguishes its use from other tools by explicitly saying to use it first when unsure what Pipeworx can do.

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

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

The description provides explicit usage scenarios ('when you do not yet know what Pipeworx can do for you' and 'to learn how to call the meta-tools') and example triggering queries. However, it does not explicitly state when not to use it or list alternative 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?

The description discloses key behavioral traits beyond annotations: ownership enforcement, deactivation vs deletion, and availability of historical events via recent_alerts. This aligns with and augments the annotations (idempotentHint, destructiveHint, readOnlyHint).

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) with no redundant information. It front-loads the main action and efficiently covers ownership, mode of action, and data persistence.

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

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

For a simple tool with one parameter and no output schema, the description fully covers what the agent needs: the action, ownership constraint, side effects, and references to related tools (recent_alerts). It is complete and actionable.

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

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

With 100% schema coverage, the description adds value by linking the 'id' parameter to the 'subscribe' tool, providing context that the schema alone does not offer.

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 'Cancel' and the resource 'subscription by id', distinguishing it from siblings like 'subscribe' and 'list_subscriptions'. It also adds specifics about ownership and data behavior.

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

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

The description provides clear context by stating ownership enforcement ('only cancel your own subscriptions') and the effect on data (deactivated, not deleted). However, it does not explicitly exclude alternative tools or provide 'when not to use' guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior, and the description adds significant context: the full verdict set, the critical meaning of could_not_verify (not evidence, not a refutation), unsupported semantics, and the exact percent-delta math for financial claims. This goes well beyond the annotations and greatly helps callers interpret results correctly.

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

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

The description is fairly long but every sentence earns its place, covering trigger phrases, usage context, routing logic, return contract, error handling, and efficiency gains. It is front-loaded with natural language triggers and the core use case. The only slight redundancy is the final 'replaces 4–6 sequential calls' note, but it underscores the tool's 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?

With no output schema provided, the description carries the full burden of explaining return values, and it does so thoroughly: verdict types, grounded/structured actual value with citations, reasoning, and error metadata. It also covers edge cases (could_not_verify vs. unsupported) and the two distinct pipelines. This is a complete and highly actionable description for a complex tool.

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

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

The input schema already covers 100% of parameters with detailed descriptions, including tolerance_pct's behavior and examples. The description adds some context about the exact percent-delta math and fallback routing but does not materially alter or add to the parameter semantics beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly defines the tool as natural-language claim verification against authoritative sources, with explicit trigger phrases like 'fact check' and 'verify the claim that…'. It distinguishes itself from sibling tools like ask_pipeworx_grounded by focusing on validating factual claims and replacing multi-step pipelines, making the purpose unmistakable.

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

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

The description explicitly states when to use the tool: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing for company-financial claims vs. other claims. However, it does not name alternative tools to use instead (when-not), which is a minor gap for full usage guidance.

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