Phishtank

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

Annotations already declare read-only, idempotent, non-destructive. The description adds value by disclosing that Anthropic probing requires a BYO API key passed to api.anthropic.com, and by describing the output structure (per-model score, confidence, signals, raw_response + combined view). No contradictions.

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

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

The description is concise and efficient: one paragraph with sentences covering purpose, default model, API key usage, output structure, and use cases. No redundant or wasted words.

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

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

The description covers purpose, model selection, API key handling, and output structure. It is sufficient for a tool with 4 parameters and no output schema, though it omits potential rate limits or latency considerations that could be relevant for an agent.

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

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

Schema coverage is 100%, so baseline is 3. The description clarifies the default model (Workers AI Llama-3.3-70b) and API key requirement, but does not add parameter-level meaning beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score per model. It distinguishes from sibling tools like 'bet_research' and 'check_url' which 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 indicates clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) but does not explicitly state when not to use or how it differs from similar siblings like 'scan_competitor_ai_presence'. It provides clear context without exclusions.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by stating it returns structured answers with stable pipeworx:// citation URIs and that it fills arguments automatically.

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

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

Front-loaded with key instruction, then elaborates with examples and usage boundaries. Every sentence adds value, though the description is somewhat lengthy at ~150 words.

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

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

For a complex tool with 6 parameters, no output schema, and many siblings, the description thoroughly covers purpose, usage, triggers, and alternatives. Does not detail return format beyond 'structured answer with citations', which is adequate.

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

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

Schema coverage is 100%, documenting all 6 parameters (5 aliases plus question). The description provides examples and confirms natural language input, but does not add meaning beyond what the schema already provides.

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

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

The description specifies the tool routes questions to 5,008 tools across 1,318 sources for factual data, lists concrete domains (SEC, FDA, FRED, etc.), and distinguishes from siblings like ask_pipeworx_grounded and deep_research.

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

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

Explicitly states 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', provides when-not-to-use with specific alternatives (ask_pipeworx_grounded for single high-confidence answers, deep_research for broad queries), and lists query trigger phrases.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specific behavioral detail: source-preference ranking, candidate improvements, experimental edge. 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 well-structured sentences, front-loaded with key info (beta, universal router, improvements). Uses bold for emphasis, 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 mentions same response shape and result comparison. For a complex tool, it's fairly complete. Minor lack of edge cases but acceptable for beta.

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

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

Schema has 6 parameters (question and 5 aliases), all described as aliases with 100% coverage. Description adds no additional parameter meaning beyond 'same arguments'—baseline 3 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's a beta version of ask_pipeworx, a universal router with 5,008 tools, same arguments and response shape. It distinguishes from sibling ask_pipeworx by being the experimental edge with source-preference ranking.

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

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

Explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against stable router. Also clarifies it falls back to nothing and is a full working router.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds key behavioral details: returns structured refusal reasons (not_in_source, no_tool_match, etc.), uses only tool result (anti-hallucination), and costs one extra LLM call. 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, starting with purpose, then mechanism, then usage guidance. Every sentence adds value, though it is slightly verbose (e.g., listing refusal reasons inline could be shortened). No wasted verbiage, but could be trimmed for extreme conciseness.

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

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

Given the complexity (routing across 5008 tools) and no output schema, the description fully explains return format (answer, evidence, etc.) and all possible refusal reasons. Covers when to use, trade-off with ask_pipeworx, and the anti-hallucination guarantee. Complete for an agent to select and invoke correctly.

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

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

Schema coverage is 100% with all parameters as aliases for 'question' described. The description does not add new parameter-level semantics beyond what the schema provides (e.g., format or constraints). It only contextualizes how the question is used, which is helpful but not adding to parameter understanding.

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

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

The description clearly states it is a 'Hallucination-resistant answer mode for high-stakes reads' and explains the mechanism: picks the right tool, fetches data, extracts answer using only the result. It distinguishes itself from the sibling ask_pipeworx by noting the same routing but an extra extraction step.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Also provides when-not-to-use: 'prefer ask_pipeworx for casual lookups' due to extra cost. Names ask_pipeworx as an alternative.

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

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

Annotations declare readOnlyHint, idempotentHint, destructiveHint. Description adds extensive behavioral details: resolution confidence levels, parent event extraction, news fallback, safety short-circuits, spread liquidity warnings, cancellation rule parsing. 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?

Well-structured with clear sections: purpose, usage, classifiers, fan-out examples, response shapes. While verbose, every section adds value. Front-loads key info.

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

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

No output schema, but description thoroughly documents response fields, edge cases (low confidence, closed markets, wide spreads, cancellation rules), and safety mechanisms. Complete for a research 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 100% with descriptions for all 3 params. Description enriches meaning with examples of depth enum, include_raw implications, and market input variations. Adds context beyond schema.

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

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

Description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It provides specific examples of input types and output structure, and distinguishes from siblings like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly states use cases: 'should I bet on X', 'what does the data say about Y', 'is there edge in Z'. Provides category-specific fan-out examples. Does not explicitly exclude alternatives, but context makes usage 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds value by specifying return fields (phish status, verification, details URL), enhancing transparency without contradiction.

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

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

Two succinct sentences with an example. Every sentence contributes value; no wasted words. Front-loaded with purpose.

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

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

Given low complexity (1 param, rich annotations) and output schema presence, the description adequately explains functionality and return values. Lacks explicit mention of rate limits or authentication, but annotations cover safety.

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 the parameter 'url' documented. The description provides an additional example but adds minimal semantic depth beyond what the schema already provides.

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

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

The description clearly states the tool checks if a URL is a known phishing site in the PhishTank database. It specifies a specific verb ('check'), resource ('URL'), and context ('PhishTank database'), distinguishing it from sibling tools.

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

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

The description implies usage for phishing checks via an example but does not explicitly state when to use vs alternatives or when not to use. However, no sibling duplicates the purpose.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds useful behavioral details: uses SEC EDGAR/XBRL, handles off-calendar fiscal years, returns paired data with citation URIs, and replaces many sequential lookups. Minor omission: no mention of data freshness or rate limits.

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

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

Description is somewhat long but efficiently packs critical info. Front-loaded with triggers and usage guidance. Slightly verbose but 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?

Thoroughly covers two entity types, data sources, sorting, and output format. No output schema exists, so description compensates well. Complete for the tool's complexity.

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

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

Schema coverage is 100%. Description explains each parameter's enum values in detail, specifies what data each type pulls, clarifies max/min items, and adds 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?

Starts with natural language triggers and clearly states it performs side-by-side comparison of 2–5 companies or drugs in one call. Specifies data sources per type and distinguishes from single-entity tools like entity_profile.

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

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

Explicitly advises ALWAYS PREFER over sequential single-pack lookups when comparing entities, and gives example user queries. Provides clear context for when to use this tool vs alternatives.

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

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

Disclosures beyond annotations: account requirement, data source count, parallel decomposition, return format (evidence, confidence, source, citations, gaps, contradictions), latency ranges, hop field, semantic excerpting. No contradiction with annotations (readOnlyHint, openWorldHint, etc. are consistent).

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

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

The description is comprehensive and front-loaded with critical account info. However, it is lengthy and could be more structured with bullet points or sections. Every sentence adds value, but brevity could improve readability.

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

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

Given no output schema, the description fully explains the return format (findings packet with evidence, confidence, source, citation, gaps, contradictions). Covers constraints (structured data only, not open-web), latency, depth behaviors, and iteration. No missing information for effective use.

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

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

Schema coverage is 100% for both parameters. The description adds value by explaining depth enum values (quick=3 facets, standard=5 with gap recovery, thorough=8 with iterative hop) and noting question should be in natural language. However, the schema already provides enums and descriptions, so the added value is moderate.

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 grounded multi-source research across 1318 structured data sources, decomposing questions into facets and routing to 5008 tools. It explicitly distinguishes from siblings like ask_pipeworx by noting it is not open-web search and is for broad/multi-part 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?

Provides explicit when-to-use scenarios (broad/multi-part questions) and when-not (single lookup or breaking news). Names alternatives: ask_pipeworx for single lookup or current news, and mentions account requirements with a free tier and paid plan for thorough depth.

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, idempotentHint=true, and destructiveHint=false. The description adds valuable context: the tool returns 'the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that each result is 'ready to call directly, no second schema lookup needed.' This goes beyond annotations by clarifying the output richness and readiness. No contradictions.

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

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

The description is three sentences, each serving a clear purpose: stating the action, listing usage scenarios, and describing the return value. No extraneous words. Front-loaded with the core purpose. Very efficient.

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

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

Given that there is no output schema, the description adequately explains what the tool returns (top-N tools with schemas) and how to use it (natural language query, optional limit). The 6 parameters and aliases are covered. Could optionally mention pagination or exact response structure, but it's not essential for an agent to 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 description coverage is 100% with all 6 parameters documented. The description reinforces that 'query' accepts natural language and lists aliases (task, q, description, search) which matches the schema. However, it does not add new semantic 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 starts with 'Find tools by describing the data or task' and provides numerous domain examples (SEC filings, FDA, etc.). It clearly states the tool's purpose: to discover relevant tools. The sibling context shows many other tools, and this one is positioned as a discovery-first step, distinguishing it from specific action tools.

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

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

Explicit guidance is given: 'Use when you need to browse, search, look up, or discover what tools exist'. It also says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This directly tells the agent when to invoke 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 indicate read-only, idempotent, and non-destructive behavior. Description adds significant context: parallel fan-out across multiple sources, soft-fail for patents due to sunset, and detailed output fields. 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 well-organized with front-loaded examples, clear bullet points, and no unnecessary sentences. Every sentence provides useful information about functionality or 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?

Given the complexity of the tool (multiple sources, multiple output fields), the description covers all key aspects: input constraints, output structure, data sources, limitations (patent sunset), and fallback behavior. No output schema but description sufficiently describes returns.

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

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

Schema coverage is 100% with good descriptions for both parameters. Description reinforces the name limitation and provides examples, adding marginal value but not essential beyond schema.

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

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

Clearly states it returns a full cross-source profile of a US public company. Provides example queries and explicitly lists the data sources and output fields. Distinguishes from chaining multiple tools.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack lookups' when a holistic view is needed. Also advises using resolve_entity if only a name is available, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, which align with 'delete'. The description adds no additional behavioral context beyond the annotations, such as reversibility or permission requirements. 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?

Three sentences, front-loaded with the primary action, and no superfluous information. Every sentence earns its place.

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

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

Given the tool's simplicity (one parameter, no output schema), the description covers purpose, usage, and relation to siblings thoroughly. No gaps.

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

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

Schema coverage is 100% with one parameter 'key' described as 'Memory key to delete'. The description does not add further meaning to the parameter beyond what the schema provides.

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

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

The description explicitly states the action 'Delete a previously stored memory by key', specifies the resource (memory by key), and distinguishes from sibling tools by mentioning 'Pair with remember and recall'.

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

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

The description provides clear when-to-use scenarios: 'when context is stale, the task is done, or you want to clear sensitive data'. It also pairs with remember and recall, implying alternatives, but lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, indicating safe, non-destructive behavior. The description adds value by explaining exactly what happens: fetches the page, extracts title/description/key links, and emits standard format. It also notes the output is a single text blob ready for deployment. This goes beyond annotations and gives the agent a clear behavioral model.

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

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

The description is extremely concise: three short sentences plus a 'Useful for:' list. It front-loads the core function ('Generate a production-ready llms.txt file for any URL') and uses no filler. Every sentence serves a purpose, making it easy for an agent to parse quickly.

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 simplicity of the tool (2 params, no output schema, annotations covering safety), the description is largely complete. It explains the input, process, output, and use cases. It does not cover error handling or edge cases (e.g., invalid URL), but for this straightforward tool, that is acceptable. A minor gap is the lack of output format details beyond 'standard llms.txt markdown', but the context is sufficient.

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

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

Schema coverage is 100% with clear descriptions for both parameters (url and max_links). The description implicitly references the parameters but does not add new semantics beyond the schema. For example, max_links is mentioned in the schema as default 25, but the description does not elaborate further. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: generating a production-ready llms.txt file for any URL, specifically for AI crawlers. It details the process (fetching, extracting title/description/key links) and the output format (standard llms.txt markdown). This distinguishes it from sibling tools like check_url or scan_competitor_ai_presence by focusing on the specific llms.txt resource.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor AI visibility. While it doesn't explicitly exclude alternatives or define when not to use, the context is clear and helps an agent decide when this tool is appropriate. It could be improved by mentioning alternatives like check_url for general fetching, but it's still strong.

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

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

Annotations already declare readOnlyHint and destructiveHint, so the safety profile is clear. The description adds return fields but no additional 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 with clear structure: purpose first, then return fields, then 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?

Given the simple nature, one optional parameter, and rich annotations, the description covers what is needed: purpose, return fields, and usage context.

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

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

Schema coverage is 100% with a self-explanatory parameter description. The description does not add extra meaning beyond the schema, meeting 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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Clearly indicates when to use, but does not explicitly mention alternatives.

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

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

The description discloses behavioral traits beyond annotations, such as being free, not counting against the tool-call quota, and being rate-limited to 5 per identifier per day. These details add value beyond the annotations, which only indicate non-readOnly, non-destructive, etc.

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 at 4-5 sentences, front-loaded with purpose, followed by usage guidance and constraints. Every sentence is informative and free of 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?

The description fully accounts for the tool's complexity, with 3 parameters fully described in schema, no output schema required, and additional context on rate limits and intended use. It is complete for selecting and using this feedback tool effectively.

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

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

The input schema has 100% description coverage, with clear explanations for each parameter (type, context, message). The description reinforces the intended use of the message field but does not add substantial additional meaning beyond what the schema already 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 title and description clearly state that this tool is for sending feedback to the Pipeworx team. It specifies the types of feedback (bug, feature, data_gap, praise) and distinguishes itself from sibling tools, which are primarily query/analysis 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 tells when to use the tool: when a tool returns wrong data (bug), when a desired tool is missing (feature/data_gap), or for praise. It also provides negative guidance, such as not pasting the end-user's prompt and describing issues in terms of Pipeworx tools/packs. Additional constraints like rate limits and quota are included.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds data source (CF analytics-engine), caching behavior (5min-1h), and no PII assurance—valuable beyond annotations.

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

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

Front-loaded with main output, then use cases, then technical details. No wasted words; each sentence adds value.

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

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

For a simple tool with one optional parameter and no output schema, the description covers return values, caching, data source, and use cases adequately.

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

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

Only parameter 'window' is fully described in schema (enum, description). Description adds explanatory context: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.'

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

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

Clearly states the tool returns top tools, packs, and call volume over a window. Uses specific verbs ('Returns') and resources. Distinguishes from siblings like search/chat 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?

Lists three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use case). No when-not-to-use or alternatives mentioned, but context is clear.

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

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

The description provides extensive behavioral details: the two analysis modes, semantic anchor with Jaccard threshold, partition filter, response structure, and the fill check. Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds significant context 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 detailed but well-organized with clear sections for each mode, filters, and response. Every sentence contributes useful information, though it is somewhat dense. A slightly more structured format with explicit headings could improve readability.

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 modes, internal logic, fill check), the description is remarkably complete. It explains the return values (opportunities, partition_check, fill check) and provides examples. Missing output schema is compensated by thorough textual explanation.

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?

Both parameters (event and topic) are fully described in the schema (100% coverage). The description adds value by explaining the default behavior (trending_scan), giving example values, and clarifying the semantics of each parameter 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 opens with 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks,' which clearly states the action and method. It distinguishes itself from sibling tools like polymarket_edges and polymarket_fill_risk by focusing specifically on arbitrage detection.

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 each mode (event vs topic) and what happens with no arguments. It references polymarket_fill_risk for custom sizing. However, it does not explicitly state when not to use this tool, though context is clear.

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

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

The description goes far beyond the annotations (readOnlyHint, idempotentHint, etc.), disclosing internal model details (lognormal barrier, GDELT ratio, partition overround with sport-specific alpha), caching behavior (1h KV keyed on knobs), and limitations (Fed markets excluded due to unreliable signal). It also explains diagnostics for empty segments. No contradiction with annotations.

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

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

The description is well-structured and front-loaded with the core purpose. It covers all necessary details in a logical order (overall purpose, segments, opportunity fields, knobs, response structure, caching). While it is dense and somewhat long, every sentence adds value given the complexity of the tool. A minor trim could improve conciseness.

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

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

Given the tool's complexity (9 parameters, 3 segments, no output schema), the description is remarkably complete. It explains the response structure with by_segment and diagnostics, how knobs affect results, caching, and even edge cases like Fed markets. Without an output schema, this description serves as a full specification.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add extra meaning to parameters beyond what is already in the input schema descriptions. The parameter descriptions within the schema are thorough, but the tool description itself does not enhance parameter understanding beyond that.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It uses a specific verb and resource, and distinguishes this as a discovery tool for edge opportunities. While it does not explicitly differentiate from siblings like polymarket_arbitrage, the purpose is unambiguous and actionable.

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

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

The description explicitly frames the tool for the question 'what should I bet on today' and explains that it avoids paging through hundreds of markets. It provides clear context on when each opportunity segment (model-driven, structural arbitrage, concentrated longshot) applies and mentions tradeable-edge knobs. However, it lacks explicit when-not-to-use guidance or comparisons to alternative tools among the 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?

Annotations indicate readOnly and idempotent behavior. The description aligns and enriches with details on data structure (tracked, expired, snapshot_dates), computation methods (trend, decay), and constraints (snapshot gaps, TTL), providing full transparency.

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 well-structured, starting with purpose, then detailed output, then limits. Every sentence adds value, though slightly verbose for the technical audience.

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

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

Despite lacking an output schema, the description fully defines the return structure (tracked, expired, snapshot_dates) and covers edge cases (gaps, TTL). It is thorough for a tool analyzing time-series data.

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

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

Schema coverage is 100%, but the description adds value by specifying defaults (days:14, window:'1wk') and clamping range for days, going beyond what the schema provides.

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

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

The description clearly states the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It answers a specific question and distinguishes from siblings like 'polymarket_edges' which likely provides current edges without history.

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 this tool by contrasting fresh vs old edges, implying context. It includes limits (TTL, gaps) but does not explicitly state when not to use or name 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?

Annotations declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds significant behavioral context: walks the order-book ladder, returns fill details, and warns that partial basket fills create directional risk (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?

Moderately long but all sentences are substantive. Front-loaded with core purpose and modes. Some redundancy (mode explanation repeated), but overall efficient 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?

No output schema, yet the description comprehensively lists all return fields for both modes. Covers edge cases (thin legs, forced directional risk) and explains why the tool is critical before trades. Fully compensates for missing output schema.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description adds extra value: explains mode-specific interpretations (size_usd as max spend vs target proceeds vs settlement notional), default side auto-detection for baskets, and the clamp range. This goes beyond schema.

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

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

The description clearly states the tool performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth', distinguishing between single-market and basket modes. It lists key return fields (top_of_book, vwap_fill_price, verdict, etc.) and contrasts with sibling tools like polymarket_arbitrage and polymarket_edges, making purpose unambiguous.

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

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

Explicitly states 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Explains why—partial basket fills convert arb into unhedged directional position, the dominant loss mode. Also gives mode selection criteria (market vs event).

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

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

The description adds significant behavioral context beyond annotations: explains compatibility_warning conditions, temporal alignment, and counters for skipped comparisons. Annotations already declare readOnlyHint, openWorldHint, etc., but the description enriches the agent's understanding of the tool's safety and limitations.

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

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

The description is well-structured and front-loaded with the main purpose, but it is somewhat lengthy. Every sentence adds value, though a slight trim could improve conciseness without losing critical 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 complexity (two modes, multiple safety fields, response structure) and no output schema, the description covers all necessary aspects: mode selection, parameter interplay, response fields (prices, spreads, compatibility_warning, temporal_alignment), and real-world caveats. The agent has sufficient information to use the tool correctly.

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

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

All three parameters have descriptions in the schema, but the tool description adds essential context about mode interaction (topic auto-fetch, explicit override) and provides examples. This goes well beyond the schema definitions.

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

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

The description clearly states the core function: computing the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by specifying the exact venues and modes.

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

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

Explicitly describes two modes (topic and explicit) with clear when-to-use guidance. Warns that most pre-mapped topics are not tradeable and explains when compatibility_warning fires, helping the agent decide when 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 indicate readOnlyHint=true and destructiveHint=false. The description adds behavioral details: scoping to identifier, that it retrieves rather than mutates, and pairing with remember/forget. No contradictions.

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

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

The description is concise (three sentences), efficiently front-loaded with the action, and every sentence adds value without redundancy.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description covers retrieval, listing, scoping, and pairing with siblings. It is fully adequate for correct use.

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

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

Schema coverage is 100% and includes a description for the 'key' parameter. The description adds meaning by explaining that omitting the key lists all saved keys, which is not in the schema description. This helps the agent understand the dual behavior.

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 ('Retrieve') and resource ('a value previously saved via remember' or 'list all saved keys'), clearly distinguishing it from sibling tools like 'remember' and 'forget'. It states exactly what the tool does.

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

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

The description explicitly says when to use it ('Use to look up context the agent stored earlier') and mentions scoping and pairing with remember/forget. It does not explicitly mention when not to use it or name alternatives, but the context is clear.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds beyond these: explains that setting 'mark_read:true' flags events as read so the next call shows only newer ones. This is a key behavioral trait not captured in annotations. However, it doesn't detail other side effects like rate limiting or feed consumption limits.

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

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

The description is four sentences, each serving a purpose: primary action, payload contents, filtering options, and polling/alternative. No redundant phrases. The most critical info is front-loaded. This is highly efficient.

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

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

Given the tool has 5 parameters (all documented in schema) and no output schema, the description adequately covers purpose, key behaviors, and return content (source, citation_uri, raw payload). However, it lacks explicit return structure details (e.g., pagination, field types). It is functional but not exhaustive.

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 all 5 parameters are already documented structurally. The description adds context for 'type' and 'since' (filters), and for 'mark_read' (flag read behavior), but does not elaborate on 'limit' or 'unread_only' beyond schema. The added value is moderate, justifying a 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?

The description clearly states the tool 'pulls fired events from your subscription feed' and 'returns the most recent alerts'. It distinguishes itself from siblings like 'list_subscriptions' by focusing on alert event retrieval. Specific verb 'Pull' combined with 'fired events' and 'feed' establishes a clear, specific action.

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 provides guidance: 'Polls work fine; the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This tells the agent when to use this tool (polls) vs. an alternative (HTTP endpoint for scripts). It also implies appropriate context for continuous checks.

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?

Describes fan-out to SEC EDGAR, GDELT/GNews fallback, USPTO soft-fail, and return structure with citations. Adds context beyond annotations (readOnly, openWorld, idempotent, non-destructive) 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?

Single paragraph that front-loads common queries and packs all relevant details (sources, parameters, alternatives, return structure) 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?

Even without output schema, description explains return format (changes[] grouped by source, total_changes, citation URIs) and mentions fallback/soft-fail behavior. Sibling context provides clear alternative (entity_profile).

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

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

Schema coverage is 100%, but description adds value by explaining 'since' accepts ISO dates and relative shorthand, 'value' can be ticker or CIK, and recommends typical values like '30d' for monitoring.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, with specific examples like 'What's new with X' and distinguishes from sibling tool 'entity_profile' which provides static profiles.

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

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

Explicitly tells when to use this tool (for dynamic updates) vs when to use 'entity_profile' (for static profile), and provides guidance on typical 'since' values like '30d' or '1m'.

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

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

Annotations already indicate idempotency (idempotentHint: true) and non-destructiveness. The description adds valuable behavioral context: key-value pair scoped by identifier, persistent for authenticated users, 24-hour retention for anonymous sessions. This goes beyond annotations without contradiction.

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

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

The description is concise (4 sentences) and well-structured: purpose, usage, details, related tools. Every sentence adds value; no redundancy.

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

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

For a simple 2-parameter write tool with full schema coverage and annotations, the description covers all necessary aspects: purpose, when to use, behavior (persistence, scoping), and relationships to sibling tools. No gaps.

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

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

Schema coverage is 100% with descriptions for key and value. The description does not add new parameter semantics beyond the schema; it only reinforces the key-value nature. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Save data the agent will need to reuse later'. It gives concrete examples of what to store (resolved ticker, target address) and distinguishes from sibling tools recall and forget by mentioning them as partners.

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

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

The description explicitly says when to use: 'Use when you discover something worth carrying forward... so you don't have to look it up again.' It also provides guidance on pairing with recall and forget, making it clear how this tool fits into the workflow.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint. Description adds that the tool cascades through several endpoints internally, replacing manual lookups. Does not contradict annotations.

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

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

Front-loaded with example queries, then details. Every sentence adds value. No fluff. Well-organized.

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

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

No output schema, but description fully explains return values. Covers both entity types, including citation URIs. Complete for a lookup tool with 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%. Description adds meaning beyond enums: explains return values per type, what value accepts (ticker, CIK, name for company; brand/generic for drug). Provides citation URIs.

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 ('resolve', 'look up') and resources ('name to canonical/official identifier'), clearly stating it finds tickers, CIKs, RxCUIs. It distinguishes from siblings by stating it's for when 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?

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Details supported types and what each returns. Lacks explicit when-not scenarios but provides clear context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it probes each entity via ai_visibility_check and returns ranked results with score, confidence, signal density. 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?

Three well-structured sentences. First sentence states core purpose, second details mechanics, third gives use case and output summary. 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?

With no output schema, description explains exact return format (ranked list with score, confidence, signal density). Also covers entity count constraint (2-8) in schema. Complete for a comparison 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?

All 4 parameters have schema descriptions (100% coverage). Description adds extra semantics: first entity is treated as 'subject' for narrative, rest as competitors; default model is workers-ai; _apiKey only needed if anthropic included.

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

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

Description uses specific verb 'scan and compare' with clear resource 'competitor AI presence'. Distinguishes from sibling tools like ai_visibility_check by emphasizing side-by-side comparison and ranking.

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

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

Explicitly states it is for competitive AI-marketing audits with an example question. Does not list when to avoid, but context makes usage 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 declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral traits like partial failure graceful degradation, sources_failed list, and bundlephobia timing (5-30s), which go beyond annotations.

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

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

The description is detailed but each sentence adds value. It is front-loaded with the core purpose and then expands on details. Slightly longer than necessary but remains clear and structured.

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

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

Given the complexity (multiple data sources, partial failures, timing, multiple return fields), the description is very complete. It lists return fields even though no output schema exists, addressing the information need.

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

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

Schema coverage is 100%, so baseline is 3. Description adds that scoped packages accepted and version defaults to latest, providing extra meaning beyond schema types and descriptions.

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

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

The description clearly states it's a composite check for npm packages covering license, advisories, version history, and bundle size. It uses specific verbs and distinguishes from sibling tools (e.g., deps.dev:version for other ecosystems).

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

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

Explicitly says to use when an agent asks about safety, popularity, size, or cost of adding a package. Also notes NPM-only scope and directs other ecosystems to deps.dev:version, providing clear 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?

Beyond annotations (readOnlyHint, etc.), description reveals technical details: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char limit with truncation and flagging, and that passages include character offsets for verification. No contradictions.

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

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

Concise single paragraph with clear front-loading of purpose. Every sentence adds value—usage guidance, technical details, pairing hints. 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 full schema coverage, comprehensive annotations, and no output schema needed, the description is complete. It explains input requirements, behavior, limitations, and output characteristics (top-N passages with offsets and scores).

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: explains what the query is (natural-language), mentions limit defaults, and describes the text parameter capacity and truncation behavior. This exceeds 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 explicitly states the tool performs semantic search inside a fetched record, with specific examples like SEC 10-K. It distinguishes itself from sibling tools like ask_pipeworx_grounded by describing how they pair together.

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?

Clearly states when to use: 'when the record is too big to cram into the prompt'. Provides explicit usage pattern: pass the text you already pulled plus a natural-language query. Also describes the alternative workflow with ask_pipeworx_grounded.

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 readOnlyHint=false (mutation), idempotentHint=true, and destructiveHint=false. The description confirms this by stating it creates a subscription and returns an id. It adds critical behavioral context beyond annotations: OAuth requirement, delivery channel constraints (phone verification, SMS daily cap, webhook auto-disable after 10 failures), and type-specific params. 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 somewhat long but well-structured: it starts with the core purpose, then details types and delivery options in a logical order. Every sentence adds necessary context, and the use of examples aids understanding. It is not perfectly concise, but the length is justified by the tool's complexity (multiple subscription types and delivery methods).

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

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

Given the tool has 3 parameters (one being a nested object), no output schema, but annotations present, the description covers: intended use, authentication requirements, return value (subscription id), type-specific parameter details, delivery options with constraints (phone verification, SMS cap, webhook auto-disable), and a hint at the webhook signing secret. There are no obvious gaps for an agent to misuse 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?

Schema coverage is 100%, meaning every parameter has a schema description. The description goes further: for the 'type' enum, it lists all values and explains what each type subscribes to with examples (e.g., sec_8k: ticker+items, polymarket_edge: topic). For 'params', it provides type-specific structures (e.g., fred_series requires series_id). For 'delivery', it explains differences between channels, phone verification, and webhook signing details (HMAC, secret returned once). This adds substantial meaning beyond the raw 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 verb 'Create' and the resource 'proactive monitoring subscription', explicitly distinguishes from sibling tools like list_subscriptions and unsubscribe, and provides concrete examples (sec_8k, polymarket_edge). This is a specific, action-oriented definition that leaves no doubt about what the tool does.

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 context for when to use: 'Requires a Pipeworx OAuth account' and 'anonymous + BYO cannot persist subscriptions'. It also distinguishes delivery channels (always-on feed vs optional email/sms), and includes constraints like phone verification and a 10/day SMS cap. While it doesn't explicitly list when not to use, it implies the tool is for creating subscriptions, not for listing (list_subscriptions) or removing (unsubscribe).

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. The description adds that the tool returns category-bucketed example questions with exact tool+argument shape drawn from a live catalog, providing useful behavioral context beyond the annotations.

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

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

The description is front-loaded with example questions and organized into a clear flow: what the tool does, what it returns, how to call it. Though slightly long, every sentence serves a purpose and is well-structured.

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

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

Despite having no output schema, the description thoroughly explains the return value (category-bucketed example questions with tool+argument shape). It covers usage context, parameter behavior, and when to use the tool, making it complete for a simple onboarding 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 one optional string parameter 'topic'. The description adds a list of example topic values (finance, pharma, etc.) and explains that omitting it yields a cross-category spread, enriching the parameter's meaning 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?

The description clearly states the tool is the onboarding entry point for discovering what Pipeworx can do, listing example questions and returning category-bucketed examples. It distinguishes from siblings like discover_tools by focusing on what to ask rather than tool discovery 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?

Explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also provides guidance on arguments: 'Call with no arguments for the full spread, or pass topic to focus'. It references alternatives like ask_pipeworx, entity_profile, compare_entities, etc.

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

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

Adds value beyond annotations: explains row is deactivated (not deleted) and ownership is enforced. Annotations already indicate non-destructive and idempotent, but description provides crucial behavioral detail. No contradiction.

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

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

Two sentences, front-loaded with the core action. Every sentence adds value with no waste.

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

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

Complete for a simple one-parameter tool. Covers ownership, effect on data, and historical availability. Lacks error handling info but not necessary given the idempotent annotation and simple use case.

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

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

Schema coverage is 100% with clear description of 'id' parameter. Description does not add new meaning beyond schema, so baseline score of 3 is appropriate.

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

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

Description clearly states 'Cancel a subscription by id' with specific verb and resource. It distinguishes from siblings like 'subscribe' and 'list_subscriptions' by detailing ownership enforcement and deactivation behavior.

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

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

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'). Notes that historical events remain available via 'recent_alerts', providing context for when to use. Could be more explicit about when not to use, but 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 indicate read-only, open-world, and idempotent behavior. The description adds rich behavioral context: exact percent-delta math for financials, automatic fallback for other claims, verdict categories, citation format, and performance optimization (replaces 4-6 sequential calls). 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 a single dense paragraph but front-loaded with trigger phrases. Every sentence adds value, though it could be split into smaller sections for easier scanning. No repetition or wasted words.

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

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

No output schema is provided, so the description fully covers return values: verdict types, actual value with citation, and reasoning. It also explains the two internal pipelines. Given the tool's complexity, this is complete and enables correct invocation.

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

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

Schema coverage is 100%, but description adds substantial meaning: provides examples for 'claim' and explains how 'tolerance_pct' overrides default implied tolerance, its role in verdict grading (e.g., hallucination detection), and default behavior. This goes well beyond the schema descriptions.

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

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

The description starts with multiple natural-language triggers and clearly states the tool verifies factual claims against authoritative sources. It distinguishes between company-financial claims using a fast path and other claims falling through to a grounded pipeline, making its purpose specific and distinct from siblings.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct.' Describes two distinct pipelines for different claim types. Does not explicitly state when not to use it, but context from sibling tool names provides implicit guidance.

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