Performance Review

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

Annotations already mark it as read-only, idempotent, non-destructive. Description adds that default model is free and Anthropic requires BYO key with direct payment. No contradictions.

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

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

Three sentences, front-loaded with action and output. Every sentence adds value: what it does, default behavior, example uses. 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?

No output schema, but description fully covers return structure (per-model score, confidence, signals, raw_response + combined view). Also explains prerequisite (API key) and use cases. Adequate for complexity.

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

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

Schema covers all 4 parameters (100% coverage). Description adds beyond schema: explains default model for 'models', that '_apiKey' is for Anthropic, and 'context' disambiguates entities. Value-add over baseline 3.

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

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

Clearly states it probes LLMs for knowledge about an entity and scores visibility (0-100) per model. Distinguishes itself from sibling tools like 'scan_competitor_ai_presence' by focusing on scoring and multi-model probing.

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?

Lists explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' Does not mention when not to use or alternatives, but context is clear enough.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the description only needs to add contextual behavior. It does: routing to thousands of tools, filling arguments automatically, returning structured answers with stable pipeworx:// citation URIs, and providing data that the agent should answer from directly rather than trying to recall. There is no contradiction with the annotations.

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

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

The opening sentence front-loads the core purpose well, but the description then degrades into a rambling run-on block of conditional instructions, embedded agent directives ('LLM: you are at the final generation step'), and trailing miscellanea such as 'Official: newest-pipeworx'. It is much longer than necessary and structurally disorganized, making it harder for an agent to parse reliably.

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

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

For a complex open-world routing tool with no output schema, the description covers a great deal: domains, examples, output nature, citation URIs, and sibling routing. However, it also references tools that are not listed among siblings, such as ask_pipeworx_plan and ask_pipeworx_endpoint, and includes meta-level instructions that do not directly help selection or invocation. The result is informative but confusingly incomplete as a coherent tool contract.

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

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

Schema description coverage is 100%, so the schema already documents the question parameter and its aliases. The description adds useful examples and trigger phrases ('what is', 'look up', 'find', 'get the latest'), but it does not deeply explain parameter semantics beyond what the schema provides. 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 identifies a specific verb and resource: ask_pipeworx routes natural-language questions to 5,798 tools across 1,517 verified sources and returns structured answers with pipeworx:// citation URIs. It clearly distinguishes the tool from generic web search by listing concrete domains such as SEC filings, FDA drug data, FRED/BLS statistics, patents, and clinical trials. Even with a noisy later section, the core purpose is unambiguous and well differentiated.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH for questions about current or historical data' and 'START HERE for most questions'. It also names alternatives and their conditions: use ask_pipeworx_grounded when citations are required, deep_research for exhaustive multi-source reports, ask_pipeworx_beta for tool-use-only workflows, and web search after ask_pipeworx misses for esoteric or newly-published research. This is unusually specific and actionable.

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

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

Annotations already signal read-only, idempotent, non-destructive behavior. The description adds value by disclosing that this is a full working router, that experimental candidate routing may be live at any time, and that it currently exactly matches ask_pipeworx. There is no contradiction with the annotations.

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

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

The description is information-dense and front-loads the beta identity and identical-router relationship. The parenthetical repeats 'same' multiple times and is slightly wordy, but every sentence contributes useful context about state, usage, and behavior.

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?

It covers the tool's purpose, current operational state, relationship to the stable router, and response shape through the identical-router reference. Since there is no output schema, a bit more detail about the response would be ideal, but referencing ask_pipeworx largely compensates.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and aliases. The description adds no parameter-specific detail beyond noting arguments are identical to ask_pipeworx, which meets the baseline for a fully-covered 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 this as the beta version of ask_pipeworx: a universal router with the same 5,798 tools, arguments, and response shape. It is easily distinguished from the stable ask_pipeworx sibling as the experimental-edge alternative.

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

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

It explicitly says to use it like ask_pipeworx when you want the newest routing, and explains that results are compared against the stable router. It does not detail exclusions or compare against ask_pipeworx_grounded, but the current no-candidate state gives concrete practical guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds substantial behavioral context: exact success return shape, explicit refusal reasons, evidence as verbatim quote, and the cost of one extra LLM call. 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 but every sentence earns its place: what it does, how it returns, refusal conditions, when to use, and when not to. Key information is front-loaded with 'hallucination-resistant' and 'high-stakes reads' before moving to mechanics.

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

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

For a complex autonomous tool with no output schema, the description is notably complete. It provides the return object, the refusal reasons, the use cases, the tradeoff vs the sibling, and the grounding guarantee. An agent has enough 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?

Schema coverage is 100%, and the schema already documents the question parameter as natural language with aliases. The description adds meaning by explaining that the tool autonomously routes to the right tool and fills arguments, so the caller only needs to supply a question. This is a modest but useful enrichment.

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 this as a hallucination-resistant answer mode for high-stakes reads, distinct from ask_pipeworx and ask_pipeworx_beta. It states a specific behavior (extract answer using only tool result contents) and names the sibling it shares routing with, making the tool's 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 this tool: whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts. It also gives an exclusion and alternative: prefer ask_pipeworx for casual lookups due to the extra LLM call cost. This is model guidance.

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

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

The description discloses extensive behavioral details beyond annotations: fan-out logic, response shapes, resolver contract, parent event extraction, news fields, safety mechanisms, and cancellation rules. No contradictions with annotations (readOnlyHint, etc.) are present.

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

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

The description is long but well-structured with sections (RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with the core purpose. Some enumeration (e.g., classifier list) could be trimmed, but overall it earns its length.

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

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

Despite no output schema, the description thoroughly explains return values, edge cases (closed markets, low-confidence, wide spreads), cancellation rules, and evidence sources. It is 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?

With 100% schema coverage, the description adds significant context: examples for the 'market' parameter, explanation of 'depth' (quick vs thorough), and detailed rationale for 'include_raw' (when to use true/false and impact on response size).

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', specifying the verb (research) and resource (Polymarket bet). It distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by being a general research 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?

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"'. It also describes behavior for unsuitable cases (closed markets, low-confidence matches) and includes safety notes, though it does not explicitly state when not to use or name alternatives.

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

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

Despite annotations indicating read-only, idempotent, non-destructive, description adds valuable behavioral details: for companies, pulls specific financial metrics from SEC EDGAR/XBRL with correct fiscal year handling; for drugs, pulls FAERS counts, FDA approvals, trial counts. Also mentions sorting by primary metric and citation URIs. No contradiction.

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

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

Description is one cohesive paragraph, front-loaded with example queries. It efficiently packs details but could benefit from slight structural separation (e.g., bullet points) for easier parsing. No wasted words, though.

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 (both required, 100% covered), no output schema, the description fully explains input, behavior (including entity-specific logic), and output format (paired data with citation URIs). The agent has all necessary information 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?

Schema already describes parameters with 100% coverage. Description adds meaning: explains how 'type' determines which data is pulled, and that 'values' expects tickers/CIKs for company or drug names. Also clarifies constraints like min/max items.

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 identifies the tool's action: comparing 2-5 entities (companies/drugs) in a single parallel call, using specific verbs like 'compare', 'vs', 'rank'. It distinguishes from sibling tools like entity_profile by emphasizing multi-entity comparison.

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

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

Explicit guidance to prefer this tool over sequential single-entity lookups when comparing entities. Provides example queries and context for when to use (comparative questions). No exclusion criteria mentioned, but clear recommendation.

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?

Even though annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds substantial behavioral context: parallel routing across 5,798 tools, explicit gaps[] for unanswered facets, a guarantee that findings are never invented, hop and contradiction passes for standard/thorough depths, semantic excerpting, and expected latency of 15-60s (up to ~90s for thorough). No contradiction with annotations was found.

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

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

The description is long but front-loaded with the critical account requirement and fallback tool, and all major sections (data scope, output packet, depth behavior, latency, citation guarantees) serve the goal of correctly selecting and invoking a complex paid tool. It is dense but not bloated; each sentence contributes useful 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?

Because there is no output schema, the description carries the responsibility of explaining what the tool returns, and it does so thoroughly: verbatim evidence, confidence, source, fetched_at, stable pipeworx:// citations, gaps[], contradictions[], and hop fields. It also covers authentication, plan requirements, latency, and when to choose an alternative, so an agent has what it needs to call and interpret the tool.

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

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

Despite 100% schema description coverage, the description materially enriches parameter understanding. It explains the practical meaning of depth (quick=3 single-hop, standard=3 default with gap-recovery and contradictions, thorough=6 paid with full iterative hop) and clarifies that question accepts broad/multi-part natural language. This goes well beyond the enum values 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?

States a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1517 STRUCTURED data sources in ONE call' and explicitly distinguishes itself from open-web search. It also describes the workflow (decompose question, route to tools in parallel) and the findings packet, so an agent can clearly identify what the tool does and how it differs from siblings.

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

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

Provides explicit usage conditions: account required, depth:'thorough' requires a paid plan, and directs unsigned-in users to ask_pipeworx instead. It also states when this tool is best ('broad/multi-part questions over structured data') and when not to use it ('For a single lookup use ask_pipeworx instead'), making alternative selection unambiguous.

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 and idempotentHint true, destructiveHint false. The description adds behavioral details beyond annotations: returns top-N relevant 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?

The description is fairly concise but front-loaded with the core purpose. It includes a list of example domains which is helpful but could be slightly trimmed. Still well-organized and informative.

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 what is returned (names, descriptions, schemas with examples) and notes the limit parameter's range. For a discovery tool with high annotation coverage, this is sufficiently complete.

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

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

Schema coverage is 100%, but the description adds context by explaining that query accepts natural language descriptions like 'analyze housing market trends' and lists aliases. This enriches understanding. Slight deduction for not specifying the default limit value in the description.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists numerous specific domains and tasks (SEC filings, FDA drugs, etc.), distinguishing this discovery tool from its siblings which are specialized tools.

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

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

Explicit usage guidance: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent precisely when to use this tool vs. others.

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 substantial behavior beyond annotations: fan-out across many sources, per-section return semantics, USPTO soft-fail behavior, expected-empty FDA sections, resolved:false for private companies, and the sources_used/sources_failed audit fields. It reinforces the readOnly/openWorld/idempotent 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 long and dense, but front-loaded with trigger phrases and a clear preference directive. Each section of the return object is described with expected behavior. Some material repeats schema information, so it could be tightened slightly, but overall it is well-structured for a complex tool with no output schema.

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 carries the full burden of explaining return values. It enumerates all major output sections—cik, filings, fundamentals, patents, federal_contracts, fda_products, hiring, news, LEI, and sources_used/sources_failed—and explains edge cases like private companies and expected-empty sections. Nothing critical is missing.

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 already documents type and value with examples. The description adds value by stating that type accepts 'company' or 'ticker' interchangeably and by explaining how a private-company name resolves to resolved:false rather than a bare failure. Much is redundant with the schema, so this is strong but not a 5.

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 a clear resource: it profiles US public companies with 'full cross-source profile... in ONE parallel call.' It also distinguishes itself from chained single-pack lookups, helping an agent separate it from siblings like resolve_entity or compare_entities.

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

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

It explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states what happens for private companies, notes that person/place queries are not yet supported, and clarifies that empty result sections are expected data absence, not failures.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true. The description adds context about use cases but does not elaborate on behavior beyond deletion (e.g., error handling, irreversibility).

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

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

The description is two sentences, front-loaded with the core action, and contains no 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?

For a simple tool with one required parameter and no output schema, the description explains what it does and when to use it. It is mostly complete, though it could mention idempotency or error behavior more explicitly.

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 description 'Memory key to delete'. The tool description does not add additional meaning beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the action (Delete) and resource (previously stored memory by key). It is specific and distinct from siblings like remember and recall, which are mentioned for 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?

The description explicitly states when to use the tool: when context is stale, task is done, or to clear sensitive data. It mentions pairing with remember and recall, but does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and idempotentHint. The description adds that it fetches the page, extracts title/description/key links, and outputs a single text blob for site-root/llms.txt. This provides useful behavioral context beyond the annotations, though no rate limits or auth details are mentioned.

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 plus a bullet-style list for usage. Every sentence adds value, no fluff. Front-loaded with the core 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 only 2 parameters with 100% schema coverage, clear annotations, and a simple text output (no output schema), the description is fully adequate. It explains what the tool does, how it works, and what the output is.

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 documents both parameters. The description briefly explains the process (fetches page, extracts info) which adds context, but does not add new meaning to url or max_links 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 it generates a production-ready llms.txt file for any URL, specifying the verb (generate), resource (llms.txt file), and scope (any URL). It distinguishes from siblings like scan_competitor_ai_presence by focusing on the specific task of creating the file itself.

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

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

The description explicitly lists three usage scenarios (getting a client's site indexed, drafting for own project, auditing competitor), giving clear context. It does not mention when not to use or alternative tools, but given the specific niche, this is sufficient.

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

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

Description adds return field details beyond annotations. Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so description confirms behavior without contradiction.

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

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

Two sentences, front-loaded with purpose and usage guidance. No wasted words.

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

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

Covers purpose, returned fields, and usage context. Lacks details on ordering or pagination but sufficient for a simple list tool with good annotations.

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

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

Schema coverage is 100% with a clear description for the single parameter 'include_inactive'. Description does not add additional 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?

Clear verb 'List' specifies resource 'the caller's active subscriptions' and lists returned fields. Distinguishes from siblings like 'subscribe' and 'unsubscribe'.

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

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

Explicitly states when to use: 'to review what you're monitoring before adding more or to find an id to cancel.' Provides context but no explicit exclusions for alternatives.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. Description adds that the output 'communicates nothing clearly', explaining the satirical nature. 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 sentence front-loads the core purpose and all key parameters, with no wasted words. Efficient and clear.

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

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

Given output schema exists (context signal), the description's brief statement about return value is sufficient. All parameters are identified, and the tool's behavior is adequately described for its 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 description coverage is 0%, so description must compensate. It lists all five parameters (employee_name, role, rating, actual_performance, what_manager_wants_to_say) and implies their roles through the overall purpose. The description adds context beyond the plain schema properties.

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

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

Description clearly states it generates a satirical corporate performance review, specifying the verb 'generate' and resource 'performance review'. The tool is unique among siblings; no other sibling tool generates reviews.

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 implies the tool is for generating satirical reviews but does not explicitly state when to use vs alternatives, nor provide exclusions or alternative conditions. Sibling context shows no similar tool, leaving use case implicit.

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

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

Annotations are all false, so the description carries the full burden, and it excels. It discloses rate limits ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), the claim_token flow (returned without an account, usable later to read status), that the team reads digests daily, and that signal affects roadmap. It also warns against pasting end-user prompts. No contradiction with annotations.

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

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

The description is long but dense with necessary information. It is front-loaded with purpose, then covers when-to-use, scope restrictions, token mechanics, and operational details. Each sentence earns its place, though it could be tightened slightly by merging some clauses. The structure flows logically from purpose to usage to constraints.

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?

This is a complex tool with two modes (submitting feedback and reading replies via claim_token), nested objects, no output schema, and no useful annotations. The description covers both modes, the parameter relationships, rate limits, quota, and scope, making it complete for an agent to use correctly. Since there is no output schema, the description appropriately focuses on invocation semantics rather than return values.

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 clear description, so the baseline is 3. The description adds meaning beyond the schema by explaining how to use claim_token with a concrete example ('pipeworx_feedback({claim_token:"pwfb_…"})') and that it must be passed with no other arguments. It also contextualizes the `message` field by saying to be specific and not paste the user's prompt. The `type` enum is well-covered by the schema, but the claim_token usage tips elevate this above baseline.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses a specific verb ('tell') and resource ('Pipeworx team'), and it distinguishes the tool from sibling tools by focusing on feedback rather than research or visibility. The scope is further clarified with the exclusion of non-Pipeworx tools.

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

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

The description explicitly states when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides clear exclusions: 'ONLY for tools served by this Pipeworx connection' and directs users to file elsewhere for tools from other MCP servers. The 'Not sure?' clarification adds a practical heuristic.

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 set readOnlyHint and idempotentHint. Description adds value by explaining the data source (CF analytics-engine), privacy (no PII), and caching duration (5min-1h). 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?

Concise paragraph front-loaded with the main result, followed by use cases and technical details. Every sentence provides value with no redundancy.

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

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

No output schema, yet description clearly states what is returned (top tools, top packs, total call volume). Also covers data source, privacy, and caching. Completely adequate for the tool's purpose.

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

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

Schema coverage is 100% with a single optional parameter featuring an enum. Description reinforces the semantics: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' Adds context beyond the schema description.

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

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

Clearly states it returns top tools, top packs, and total call volume over a window. Distinguishes from sibling tools like ask_pipeworx or deep_research by focusing on trending usage rather than answering questions.

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

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

Explicitly lists three concrete use cases (discovering hot data sources, confirming canonical tool, checking alignment). Mentions caching behavior. Lacks explicit when-not-to-use but the use cases are well-defined.

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, so the description doesn't repeat those. It adds extensive behavioral context: algorithms (monotonicity violations, partition-sum), Jaccard similarity threshold, partition filter, fill check, and expected output fields. No contradiction with annotations.

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

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

The description is lengthy and detailed, but structured with sections for modes, algorithms, and output. Every sentence adds value, but it could be more concise. Front-loaded with purpose, then details.

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

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

Given the tool's complexity (2 optional params, no output schema), the description is comprehensive. It explains output fields, edge cases (placeholder filter, fill check), and provides detailed reasoning for operations. It covers all key aspects needed for correct usage.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description adds further value by explaining the meaning of event slug and topic with examples, and differentiating the behavior of each mode.

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

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

The description clearly states it finds arbitrage opportunities via monotonicity violations and partition-sum checks, with three modes: no args (trending_scan), event, and topic. It is specific about verb and resource, but does not explicitly differentiate from sibling tools like polymarket_edges, though it hints at polymarket_fill_risk for sizing.

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 each parameter: no args for trending scan, event for specific market, topic for cross-event. It explains when to use each mode and why cross-event catches patterns missed by single-event. However, it does not explicitly list when not to use this tool or alternatives among siblings.

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

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

The description goes far beyond annotations by detailing three model families, edge calculation, caching (KV level 1h), diagnostics, and filtering knobs. It explains behavioral traits like partition kelly being zero at parent level and Fed bet exclusion. No contradiction with annotations.

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

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

The description is long but well-structured with front-loaded purpose and clear sections. Every sentence adds value, though some detail could be condensed without losing essential 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?

Despite the tool's complexity (9 parameters, no output schema), the description thoroughly covers return structure (by_segment, fed_candidates, diagnostics), caching, model details, and behavioral traits. It is comprehensive enough for an AI agent to understand and use correctly.

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

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

Schema coverage is 100%, and the description adds significant context to parameters: e.g., min_kelly explains skipping small opportunities, max_spread_pp warns about edge erosion, min_liquidity describes walking the book, and min_partition_leg_kelly clarifies why min_kelly doesn't filter partitions.

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

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

The description uses a specific verb ('Scan') and resource ('top Polymarket markets') and clearly states the tool's purpose: returning opportunities where Pipeworx data disagrees with market price. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by focusing on edge scanning.

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

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

The description explicitly states it is built for 'what should I bet on today' and explains that agents can discover opportunities without paging. It provides context for when to use segments and excludes Fed bets with a rationale. However, it does not explicitly state when not to use this tool versus 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 read-only, idempotent, non-destructive. Description adds rich behavioral details: output structure, trend computation, decay formula, snapshot TTL, and data gaps. No contradiction.

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

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

Description is dense with information but somewhat lengthy; could benefit from clearer structure. However, every sentence adds value, no fluff.

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

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

Given lack of output schema, description fully explains output (tracked[], expired[], snapshot_dates[]) and covers limitations, edge cases, and computational details. 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 provides parameter descriptions (100% coverage). Description adds value by specifying defaults (14, '1wk'), clamp (2-30), and effect of parameters, going beyond the schema.

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

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

Description clearly states the tool's purpose: edge persistence and decay telemetry. It answers specific questions ('how long has this edge existed and is it shrinking?') and distinguishes from siblings like polymarket_edges and bet_research.

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

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

Description explains when to use (for checking edge persistence and decay) and implies when not (e.g., for non-persistent edge data). Does not explicitly list alternatives but mentions snapshot families and limits.

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. Description adds substantial behavioral context: walks the order book ladder, returns specific fields like slippage_pp and verdict, and warns about partial fills and forced directional risk. No contradiction with annotations.

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

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

Description is long but well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS). Information is front-loaded. Could be slightly more concise, but organization compensates for verbosity.

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

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

Given no output schema and 4 parameters, the description provides thorough coverage: explains both modes, all return fields, usage thresholds, and risk of partial fills. It fully compensates for the lack of output schema and is complete for agent to understand tool behavior.

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

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

Schema description coverage is 100%, so baseline is 3. Description adds value by clarifying interpretation of size_usd in basket mode (settlement notional, shares per leg) and explaining defaults for side in basket mode (auto). While schema covers the basics, description enriches parameter understanding.

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

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

Description clearly states it performs a realizable-vs-theoretical edge check against live order-book depth. It distinguishes two modes (single-market and basket) and lists return fields. Differentiates from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly tells when to use: before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500. Explains consequences of not using it (partial fills leading to unhedged directional risk, which is the dominant loss mode). Provides clear context and exclusions.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses substantial behavioral detail: the token-overlap matching logic, safety fields, compatibility codes, skipped leg conditions, temporal alignment semantics, fee treatment, and gross-vs-net spread caveats. This far exceeds what annotations alone provide and gives the agent a strong model of how results are produced and where to be cautious.

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 it is front-loaded with the core purpose and modes, and every sentence contributes operational or safety information. It loses one point because the sheer volume of nested caveats and code lists could be better organized with headings or bullets, and some numeric claims like '2-25pp apart' are illustrative rather than essential.

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

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

With no output schema, the description carries the full burden of explaining the response shape, fields, flags, codes, and edge cases. It covers matched spreads, skipped legs, temporal alignment, compatibility warnings, fee disclosures, and summary counters, so an agent has enough context to interpret results correctly in both modes.

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

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

Although schema coverage is 100%, the description adds significant semantics: it explains that topic maps to a pre-mapped macro list, that kalshi_event_ticker and polymarket_event_slug override the topic-mapped side, and that both modes run the identical matcher. It also explains how the parameters interact with the response and safety disclosures, making invocation decisions much more informed.

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-plus-resource statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes this from same-venue or edge-tracking tools by emphasizing the cross-venue comparison and naming the exact direction of the spread (Kalshi minus Polymarket).

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

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

The description clearly explains both usage modes: topic shortcuts for pre-mapped macros and explicit ticker/slug pairs for custom comparisons. It also provides important usage caveats, such as 'pre-mapped ≠ tradeable' and warnings about compatibility fields. It does not explicitly name sibling alternatives or say when to use them instead, so it misses the top score for alternative routing.

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=true, destructiveHint=false, idempotentHint=true. The description adds that listing all keys occurs when key is omitted, and that it is scoped to the agent's identifier. No contradictions; the description supplements the annotations.

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

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

The description is clear and well-structured, with useful context. It includes a bit of extra wording ('without re-deriving it from scratch') that adds value, but could be slightly more concise.

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

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

Given one parameter, no output schema, and full schema coverage with annotations, the description is fairly complete. It covers purpose, usage, scoping, and tool pairings, leaving little ambiguity.

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

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

Schema coverage is 100% for the single parameter 'key', with a description that matches the tool description. The description reiterates that omitting key lists all keys, but does not add significant new meaning beyond the schema.

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

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

The description clearly states that recall retrieves a value saved via remember, and that omitting the key argument lists all saved keys. The verb 'retrieve' and resource 'value' are specific, and it distinguishes itself from siblings 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 explains when to use it: to look up context stored earlier without re-deriving. It also mentions scoping (anonymous IP, BYO key hash, account ID) and pairing with remember and forget. It does not explicitly state when not to use it, but the context is clear enough.

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

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

Annotations indicate readOnly, idempotent, and non-destructive behavior. The description adds behavioral context by explaining the effect of 'mark_read' (flags events as read) and confirms polls are safe. 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 concise with no redundancy. It front-loads the core action and returns structure, then efficiently covers filtering options and usage note. Every sentence adds value.

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

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

For a read-only tool with no output schema and simple parameters, the description is complete. It explains what is returned, filtering options, side effects of mark_read, and even provides an alternative access method. No gaps.

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

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

All 5 parameters have schema descriptions (100% coverage). The description adds value by giving examples (e.g., 'type' with 'sec_8k'), explaining the effect of 'mark_read' and 'unread_only', and clarifying default values like limit=50. This exceeds the baseline.

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

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

The description clearly states the tool's purpose: 'Pull fired events from your subscription feed.' It specifies what each alert carries (source, citation_uri, raw payload) and distinguishes from sibling tools by focusing on recent alerts, while siblings like 'recent_changes' and 'subscribe' have different purposes.

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 good usage context: it explains when to use (to get recent alerts), how to filter by type and since, and mentions that polling works fine. It also gives an alternative access method via a GET URL. It doesn't explicitly exclude scenarios but the guidance is clear.

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

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

Annotations already mark as readOnly and idempotent; description adds details on data sources (SEC, GDELT, GNews, USPTO) and fallback behavior (GDELT preferred, GNews when rate-limited), with no contradictions.

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

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

Description is thorough but slightly verbose. However, it is well-structured with example queries first, then mechanism, then return format, then sibling distinction. Could trim some redundancy.

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

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

Despite lacking output schema, description specifies return structure (changes[] grouped by source, total_changes count, citation URIs) and addresses edge cases (USPTO soft-fail, fallback behavior). 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 already covers all parameters with descriptions; description enriches `since` with specific examples ('7d', '30d', '3m', '1y') and clarifies value can be ticker or CIK.

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 change feed for a company in recent N days, with example queries like 'What's new with X' and explicit differentiation from 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?

Provides explicit when-to-use guidance via example queries and directly states when to use entity_profile instead. Also gives context on window formats ('30d' for typical monitoring).

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 adds value beyond annotations: scoped by agent identifier, persistence duration (24 hours vs persistent), and pairing with recall/forget. Annotations already indicate idempotent and not destructive, so description complements well.

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

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

Four sentences, front-loaded with primary purpose. Efficient but could slightly merge repetition of 'store' idea. 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?

Covers scope, persistence, usage context, and companion tools. No output schema needed for this simple tool. Could mention success/failure feedback, but not required.

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 both parameters with descriptions. Description adds example keys ('subject_property', 'target_ticker') and elaborates on the value purpose, providing meaningful context 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?

Clear verb 'save data' with specific resource 'key-value pair'. Distinguishes from sibling tools 'recall' and 'forget' by explicitly mentioning them as companions.

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

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

States when to use: 'when you discover something worth carrying forward... so you don't have to look it up again.' Provides context on persistence for authenticated vs anonymous users. Does not explicitly state when not to use, but context is sufficient.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses important behaviors: ambiguity yields figi_candidates rather than a guess, unresolvable identifiers are explicitly listed under unresolved, enrichment degrades gracefully when GLEIF/OpenFIGI are unavailable, and the tool cascades through multiple lookup endpoints. 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 front-loaded with examples and the key 'Use FIRST' instruction, but the 'company' explanation becomes a very long, heavily parenthetical sentence that is hard to scan. While most content earns its place, the structure makes the tool more difficult to parse than necessary.

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

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

For a two-parameter tool with no output schema, the description is complete: it covers input semantics, supported types, edge cases, failure behavior, and what is returned for ambiguous names (figi_candidates) and unresolved identifiers (unresolved). Nothing critical is missing for an agent to call it correctly.

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

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

Schema coverage is already 100%, but the description adds substantial value: it explains what value means for each type, gives accepted input forms (ticker, CIK, ISIN, name), and warns against passing full noun phrases like 'revenue bonds' because trailing security-class words will not match. This goes well beyond the schema's short field descriptions.

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

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

The description clearly states the verb (resolve) and the resource (user-spoken names to canonical identifiers), and backs it with concrete example phrasings. It also distinguishes the tool from siblings by saying it supplies IDs other tools require as input and 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives explicit usage context: 'Use FIRST whenever you have a name but need an ID,' and enumerates the two supported entity types with their accepted inputs. It does not explicitly name alternative sibling tools or state when not to use this tool, but the guidance is clear enough for selection.

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 and idempotent behavior. The description adds valuable details about internal probing with ai_visibility_check, ranking, and return format (score, confidence, signal density). 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 two sentences, front-loaded with the core action, and every sentence provides essential information without redundancy.

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

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

Despite lack of output schema, the description specifies the return format (ranked list with score, confidence, signal density) and references internal dependency on ai_visibility_check, providing sufficient context for safe invocation.

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

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

Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining that the first entity is treated as the subject and the rest as competitors, guiding usage 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 compares AI visibility across multiple entities, using a specific verb ('Compare') and resource ('AI visibility'). It distinguishes from sibling tools like ai_visibility_check (single entity) by emphasizing the side-by-side comparison.

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

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

The description provides a clear use case (competitive AI-marketing audits) with an example question. It implies alternatives but does not explicitly state when not to use or directly name alternatives, leaving some ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds valuable context: bundlephobia's first measurement can take 5-30s, partial failures degrade gracefully with sources_failed field, and NPM-only restriction. 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 detailed but well-organized, with key information upfront (composite check, sources) followed by specifics. Could be slightly more concise, but every sentence adds value.

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

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

With no output schema, the description clearly lists the return fields (summary block, advisories, links, alternatives) and explains failure modes. Covers all necessary aspects for a tool of this 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% with descriptions. Description adds useful context: scoped packages accepted, version defaults to latest, and explains the composite nature. Adds value beyond schema.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, combining multiple data sources. It specifies the purpose as answering questions about safety, popularity, and size, and distinguishes from siblings by limiting to npm ecosystem in v1.

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

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

Explicitly tells when to use (agent asks about adding an npm package) and when not to use (other ecosystems should use deps.dev:version directly). Also mentions partial failures and timeout behavior.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description adds valuable context: embedding model (BGE-base-en), similarity metric (cosine), windowing (500-char overlapping), character limit (200K), truncation behavior, and output features (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?

Three sentences covering purpose, usage, and technical details. Every sentence serves a clear function, front-loaded with key info. No redundancy.

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

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

Given no output schema, the description adequately explains return format (passages with offsets and scores), limits, embedding details, and pairing advice. Complete for tool selection and 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% (all parameters described). The description adds natural-language examples for 'query' and clarifies 'text' as fetched document, exceeding baseline. 'limit' default is noted implicitly.

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

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

The description clearly states the tool performs semantic search inside a fetched record, using specific verb 'search' and resource 'record'. It distinguishes from siblings like 'ask_pipeworx_grounded' by explaining the complementary workflow.

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

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

Explicitly advises use when the record is too large for the prompt and highlights pairing with 'ask_pipeworx_grounded'. However, it does not explicitly state when not to use it.

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

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

The description goes beyond annotations by detailing delivery channel behaviors (always-on feed, SMS caps, webhook auto-disable), auth requirements, and type-specific parameters. No contradictions with annotations.

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

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

The description is well-structured with front-loaded purpose and organized sections for requirements, types, and delivery. It is detailed but could be slightly more concise without losing essential information.

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

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

Given the tool's complexity (multiple types, nested params, delivery options), the description covers all critical aspects: OAuth requirement, type-specific params, delivery details, and behavioral notes (auto-disable, signing secret). No output schema exists, but the return value is stated.

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 significant value by providing examples and clarifying semantics (e.g., item codes for sec_8k, topic for polymarket_edge), exceeding the schema's minimal descriptions.

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

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

The description clearly states the tool creates a proactive monitoring subscription to a live-data event stream and returns the subscription ID. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation.

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

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

The description provides clear context for usage, including requirements (Pipeworx OAuth account) and supported types, but does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral context: returns dynamic content from live catalog, can be called with or without topic. No contradiction.

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

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

Description is structured with example queries, purpose, category list, usage instructions. Front-loaded purpose. Slightly verbose with repeated phrasing 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?

No output schema, but description explains return format: category-bucketed example questions with tool+argument shapes. Covers topic parameter effect. Complete for this simple tool.

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

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

Schema coverage is 100% with description for topic. Description adds meaning by explaining effect of omitting vs. specifying topic and listing example values. Adds value beyond schema but schema already does heavy lifting.

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

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

The description clearly states that this tool returns category-bucketed example questions with tool+argument shapes, serving as an onboarding entry point. It distinguishes itself from siblings by being the initial discovery tool.

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

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

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools (ask_pipeworx, entity_profile, compare_entities, etc.).' Provides clear when-to-use and 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 indicate mutation and non-destructive idempotent behavior. The description adds ownership enforcement and deactivation semantics (not deletion), providing behavioral context beyond annotations.

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

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

Two sentences, no wasted words. Information is front-loaded with the key action and then behavioral details.

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

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

The description covers the effect and side effects (deactivation, ownership, historical events) for a simple one-param tool. No output schema exists, but return value is not critical for this action.

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 parameter 'id' is clearly described in the schema as 'Subscription id (uuid) returned by subscribe.' The description does not add further meaning beyond this.

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 'Cancel a subscription by id', which is a clear verb+resource pairing. It distinguishes itself from sibling tools like 'subscribe' (creates) and 'list_subscriptions' (lists).

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 mentions ownership enforcement and that the row is deactivated (not deleted), implicitly guiding usage. It references 'recent_alerts' for historical events, but does not explicitly 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?

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description gives crucial behavioral context: the distinction between 'could_not_verify' (check did not happen, not evidence) and 'unsupported' (no source covers it), the routing to live vs structured sources, and the exact percent-delta math. This materially helps the agent 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 dense with useful information: examples, routing, verdict list, error semantics, and efficiency note. It is a bit long, but every sentence serves a purpose. The 'IMPORTANT for callers' callout is well-structured for the key caveat. Slightly verbose but appropriate 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?

Even without an output schema, the description covers the return value (verdict, actual value, citation), enumerates all verdict types, explains the critical error semantics, and clarifies the two fallback paths. It leaves no major ambiguity about what the agent should expect when invoking this tool.

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

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

Schema coverage is 100% with descriptions for both claim and tolerance_pct. The description adds value by providing example claims and explaining that tolerance_pct can be set to 1-2 for hallucination detection, which is not in the schema. It doesn't fully compensate for the range details, but adds enough to go above baseline.

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

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

The description clearly identifies the tool as natural-language claim verification ('fact check', 'verify the claim'), with explicit usage examples and a distinct output (verdict + evidence). It differentiates from sibling tools by mentioning the SEC EDGAR + XBRL fast path and the grounded pipeline, and by stating it replaces 4–6 sequential calls.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides conditional routing guidance (financial vs other claims). However, it does not explicitly name alternative sibling tools (e.g., ask_pipeworx_grounded) or state when NOT to use it, which prevents a 5.

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