uiule

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these, such as the default free model, BYO key requirement for Anthropic, and the per-model return format. 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 a concise paragraph of four sentences. It front-loads the action and output, includes critical context, and avoids any fluff. 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 has 4 parameters and no output schema, the description provides a clear return format and usage examples. It covers purpose, usage, parameters, and return structure adequately, though it could mention error handling or rate limits.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining the default model, that _apiKey is only needed if 'anthropic' is in models, and that context helps disambiguate common names. This adds value beyond the schema.

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

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

The description clearly states the verb 'Probe', the resource 'LLMs for what they know about a business/brand/product/topic', and the output 'score (0-100) per model'. It distinguishes itself from sibling tools by focusing on AI visibility scoring, which is unique among the listed siblings.

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

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

The description explicitly states when to use the tool: 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring.' It implies the context but does not explicitly state when not to use it or provide alternatives, missing a bit of guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint. The description adds value by explaining it routes questions to specialized tools, fills arguments, and returns structured answers with stable 'pipeworx://' citation URIs. 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 lengthy but well-structured: starts with a strong directive, lists domains, explains functionality, provides usage guidelines and examples. Every sentence earns its place, though a slight 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?

For a complex meta-tool, the description covers all necessary aspects: what it does, when to use, examples, alternatives, and output format (citation URIs). It is complete given the tool's role as a default entry point.

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 clearly described as aliases for the natural language question. The description does not add beyond the schema; it merely confirms the parameter purpose. 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 answers factual questions by routing to 4,770 tools across 1241 sources. It specifies its scope (SEC filings, FDA data, etc.) and distinguishes itself from siblings like ask_pipeworx_grounded and deep_research as the default entry point.

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

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

Explicitly contrasts with web search and siblings: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with specific alternatives. Provides concrete examples of when to use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant context: it extracts answer only from tool result, returns structured response with {answer, evidence, confidence, source, fetched_at, refusal_reason}, and specifies refusal reasons. Also mentions cost (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 concise and well-structured: first sentence states purpose, second explains mechanism, third details return format, fourth gives usage guidelines, fifth mentions cost and preference. Every sentence earns its place 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?

Considering the tool's complexity (6 parameters mostly aliases, no output schema but description outlines return object), the description is complete. It covers purpose, usage, behavioral traits, parameter semantics (via schema), return structure, refusal reasons, and cost. No gaps given the context.

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

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

Schema description coverage is 100% with all parameters having descriptions (including aliases). The description does not add extra semantics beyond what the schema provides; it only mentions 'question' parameter and its aliases. Therefore baseline score of 3 is appropriate.

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

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

The description starts with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating the tool's purpose. It explains it routes queries, picks tools, fetches data, and extracts answer using only the tool result. It distinguishes from sibling ask_pipeworx by noting the same routing but with grounded extraction. Provides specific use cases: financial verdicts, legal claims, medical lookups, public statements.

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. Gives clear alternatives (ask_pipeworx) and context (high-stakes vs. casual).

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

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

Despite annotations already indicating readOnlyHint (true) and idempotentHint (true), the description discloses extensive behavioral traits: bet classification, parallel fan-out, evidence packet structure, market match confidence levels, status codes (low_confidence_match, market_closed_or_inactive), safety mechanisms (short-circuit on low confidence), spread warnings, and resolution rule parsing. 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 a single dense paragraph with many details, examples, and technical specifics. While informative, it lacks structure (e.g., bullet points or sections) and is verbose. The core purpose is front-loaded, but brevity is sacrificed for completeness. It earns its length but could be more organized.

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

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

Given the complexity of the tool (multiple input types, classification into 16+ categories, parallel fan-out with specific data sources, various response shapes, error handling, and resolution risks), the description is remarkably thorough. It covers inputs, process, outputs, edge cases (closed markets, low confidence), and safety checks. No output schema exists, so the description fully compensates.

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

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

Schema coverage is 100%; each parameter has a description. The description adds value beyond the schema by explaining default depth ('thorough'), recommended include_raw usage ('false'), and clarifying the market parameter with examples and the fact it can accept slugs, URLs, or question text. This extra context justifies a score above 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 opens with a clear verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies three distinct input types (slug, URL, question text) and lists specific use cases. It clearly distinguishes from sibling tools like polymarket_edges or polymarket_arbitrage by focusing on single-bet research and evidence gathering.

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

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

The description explicitly states when to use: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It provides examples of fan-outs for different bet categories. However, it does not explicitly mention when not to use or compare to alternatives among siblings, though the use cases are clear enough.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds specifics: pulls latest 10-K data from SEC EDGAR/XBRL, handles off-calendar fiscal years, returns sorted results, and provides citation URIs. No contradiction with annotations.

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

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

Description is a single paragraph but front-loaded with query examples. Every sentence provides useful information. Could be slightly more structured, but overall efficient and not overly verbose.

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

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

Given no output schema, the description explains that output includes paired data and citation URIs per entity. With only 2 parameters and no nested objects, this level of detail is sufficient. It covers input, behavior, and return value nature.

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

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

Schema coverage is 100% (both parameters described), baseline 3. Description adds meaning beyond schema: explains that for 'company' it pulls specific financials (revenue, net income, cash, long-term debt) and for 'drug' it pulls adverse-event counts, FDA approvals, active trials. Also clarifies that values can be tickers/CIKs or drug names.

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 does side-by-side comparison of 2-5 companies or drugs in one call, with examples like 'compare X and Y' or 'rank these companies'. It distinguishes itself from sequential single-entity lookups, which is a sibling tool's purpose.

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 instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities'. Provides concrete example queries and explains when to use company vs drug type. No ambiguity.

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

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

Beyond annotations (readOnly, idempotent, etc.), description discloses return format (findings packet with evidence, confidence, source, citations, gaps[]), parallel decomposition, expected latency (15-60s), and that it never invents answers. No contradiction with annotations.

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

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

Description is comprehensive but well-structured with clear sections and front-loaded critical info (account, alternatives). Every sentence adds value, though length could be slightly reduced without losing clarity.

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?

Compensates for lack of output schema by detailing return structure (evidence, confidence, source, etc.) and explaining when results may be empty (non-structured topics). Lacks mention of pagination or rate limits, 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 descriptions, so baseline is 3. Description adds value by explaining depth enum implications (quick=3, standard=5, thorough=8 facets) and that depth:thorough requires a paid plan, going 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 explicitly states the tool performs 'grounded multi-source research' across 1241 structured data sources, distinguishing it from open-web search. It clearly differentiates from siblings like ask_pipeworx by highlighting its ability to decompose broad/multi-part questions into parallel facets.

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 ('best for broad/multi-part questions over structured data') and when-not-to-use (single lookup or breaking news, directing to ask_pipeworx). Also specifies account requirements and paid plan needed 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds significant behavioral context beyond annotations: 'Returns the top-N most relevant tools with names, descriptions, and full input schemas (with curated examples) — each result is ready to call directly, no second schema lookup needed.' This explains the output and side-effect-free nature. It also mentions the limit parameter. Good value-add, though no pagination or error handling details.

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

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

The description is front-loaded with the core purpose in the first sentence, followed by use cases and output behavior. It is clear and concise, with no redundant or irrelevant sentences. A minor trim could remove the alias list from description (since schema covers it), but the examples justify the length. Overall well-structured for an AI agent.

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

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

Given the tool has 6 parameters (all documented), no output schema, and no nested objects, the description covers the essential aspects: what it does, when to use it, and what the output looks like. It explains that results include full schemas ready to call, which is important for an agent. However, it omits details on error handling (e.g., query too vague) and does not specify the ranking logic. Still, adequate for a discovery tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by listing all aliases (q, task, search, description) for the query parameter and providing concrete examples like 'look up FDA drug approvals' and 'analyze housing market trends'. This goes beyond the schema's generic description and helps the agent formulate effective queries.

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' which is a specific verb+resource combination. It then lists numerous concrete data/task types (SEC filings, financials, FDA drugs, etc.) and distinguishes this tool from siblings by stating 'Call this FIRST when you have many tools available and want to see the option set' – clearly positioning it as a meta-search tool rather than a specific data tool.

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

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

Explicit guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent when to use it (exploration) and implicitly when not to (when a specific tool is already known). No alternative tools are named, but the sibling list is large and includes many specialized tools.

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

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

Beyond annotations (readOnly, idempotent, non-destructive), the description details the multi-source fan-out, specific return fields, and a known soft-failure for patents (USPTO sunset). This adds significant behavioral context.

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

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

The description is moderately concise, front-loading with example queries. Each sentence adds value, though it could be slightly shorter without losing clarity. Structured effectively.

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 data sources, potential failures), the description is thoroughly complete, listing all returned components and limitations. No output schema exists, but the description adequately covers expected return values.

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

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

Schema coverage is 100%, but the description adds that value accepts ticker or zero-padded CIK, that names are not supported, and that type is currently limited to 'company'. This extra guidance enhances 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 provides multiple example queries and explicitly states it builds a full cross-source profile of a US public company. It clearly distinguishes from sibling tools by advising preference over chaining individual lookups.

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

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

It explicitly states when to use: for holistic queries about a company, and when not to: names are not supported, recommending resolve_entity first. It also clearly prioritizes this tool over chaining other lookups.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds minor context about clearing sensitive data, but does not elaborate on consequences or error handling beyond the obvious deletion operation.

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: action, usage guidance, pairing suggestion. No wasted words, front-loaded with the core purpose.

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

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

Given the tool's simplicity (1 required parameter, no output schema), the description covers purpose, usage, and pairing. It lacks details on return values or error states, but these are not critical for a straightforward deletion 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% and describes 'key' as 'Memory key to delete'. The description does not add additional meaning or syntactic details beyond the schema, resulting in a baseline score.

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 'Delete a previously stored memory by key', specifying the verb, resource, and distinguishing the tool from siblings like 'remember' and 'recall'.

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

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

Explicitly lists when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also advises pairing with 'remember' and 'recall', providing clear context and sibling differentiation.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive nature. Description adds process details (fetches page, extracts title/description/key links, emits markdown) that align with annotations and provide extra behavioral context.

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

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

Description is a single paragraph of three sentences with clear structure: purpose first, then process, then use cases. No redundant information or unnecessary detail.

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 straightforward nature (fetch, extract, output), the description covers purpose, process, output format, and use cases comprehensively. No output schema needed as description indicates single text blob output.

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

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

Schema coverage is 100% with both parameters described. Description mentions URL input and implies max_links via 'extracts key links' but does not add new semantic information beyond the schema, meeting baseline for high coverage.

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 generates an llms.txt file for AI crawlers, specifies output format (standard markdown ready for site-root/llms.txt), and distinguishes from siblings like ai_visibility_check by focusing on file generation rather than visibility checking.

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

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

Description provides three explicit use cases (client's site indexing, own project drafting, competitor auditing) but does not explicitly exclude when to use alternatives or mention when not to use this tool.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds translation options but no further behavioral traits.

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

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

Two sentences, front-loaded with purpose, no wasted words.

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

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

Simple tool with output schema, good annotations. Description covers all necessary aspects for an agent to invoke correctly.

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

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

Schema coverage 100% with descriptions for both parameters. Description reiterates choice of translation and example translations but adds minimal new semantic meaning.

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

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

Clear verb 'Get' + specific resource 'Bible passage' + translation options. Distinguishes from siblings like get_verse and random_verse.

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

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

States it returns full text and metadata for chosen translation, but no explicit guidance on when not to use vs alternatives.

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

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

Annotations already indicate read-only, open-world, idempotent behavior. The description adds that it returns verse text in World English Bible translation, providing 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, front-loaded with purpose and examples. Every sentence is essential and informative.

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

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

The tool is simple with one parameter, annotations, and an output schema. The description covers the key aspect (returns verse text in a specific translation) and does not need to explain return values.

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

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

Schema coverage is 100% and includes examples and description for the 'reference' parameter. The tool description repeats those examples but adds no new semantics beyond the schema.

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

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

The description clearly states it 'Get a specific Bible verse or range by reference' with explicit examples. This distinguishes it from siblings like 'get_passage' or 'random_verse' by focusing on specific references and ranges.

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 examples of valid references but does not explicitly state when to use this tool over alternatives like 'get_passage' or 'random_verse'. No guidance on when to avoid using it.

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

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

Annotations already declare readOnlyHint and idempotentHint. The description adds detail about default behavior (active only) and field names. No contradiction.

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

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

Two sentences: first explains purpose and return fields, second gives usage guidance. No fluff, front-loaded with key information.

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

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

For a simple list tool with good annotations and full schema coverage, the description lists return fields and gives usage context, making it complete.

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

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

Schema coverage is 100%, and the description does not add extra meaning beyond the schema's parameter description. 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 lists the caller's active subscriptions with a specific verb and resource, and lists the return fields. It distinguishes from siblings like subscribe and unsubscribe.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for usage.

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

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

Discloses rate limit (5 per identifier per day), cost-free usage, and that it doesn't count against tool-call quota. 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?

Slightly verbose but well-organized with clear sections. Every sentence adds value; could be tightened slightly.

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 explains the outcome (team reads digests, affects roadmap) and covers all necessary context for a feedback 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?

Adds meaning beyond the input schema by explaining how to structure feedback (refer to Pipeworx tools/packs) and elaborating on the 'type' enum values.

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

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

The description clearly states the tool's purpose: reporting bugs, feature requests, data gaps, or praise to the Pipeworx team. It distinguishes the tool from siblings by its unique feedback function.

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 specifies when to use each feedback type (bug, feature, data_gap, praise) and advises against pasting end-user prompts. Provides context about team response and roadmap impact.

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. The description adds value by explaining the data source (CF analytics-engine), privacy (no PII), caching (5min-1h), and return format (pack, tool, count). This fully discloses behavioral traits 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 three focused sentences plus a bullet list, each sentence serving a distinct purpose: what it does, how to use it, technical details. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description fully explains the return values, data source, caching behavior, and alignment with user goals. No missing information for an agent to decide and invoke correctly.

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

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

Schema coverage is 100% with a good description for the 'window' parameter. The tool description reinforces the meaning by linking windows to use cases (shorter for hot, longer for steady-state). This adds contextual value beyond the schema alone.

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

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

The description clearly specifies the tool's function: it returns trending tool/pack usage from other AI agents on Pipeworx. The verb 'returns' and resource 'top tools, top packs, total call volume' are explicit. It distinguishes itself from siblings by focusing on aggregated usage data, not individual queries or tool discovery.

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 three concrete use cases: discovering hot data sources, confirming canonical tools, and checking alignment. While it does not explicitly name alternative tools to avoid, the use cases imply when to use this tool versus others. This is strong guidance, but could be improved with explicit 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 (readOnlyHint=true, idempotentHint=true) already indicate safety, but description adds rich behavioral details: walks child markets, computes partition checks, Jaccard similarity threshold, placeholder filter, fill check with book depth. 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 comprehensive but somewhat verbose. However, it is well-structured with clear sections (modes, semantic anchor, partition filter, fill check) and each sentence adds value. Could be slightly more concise but remains effective.

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

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

Despite no output schema, description explains the response structure (opportunities[] with gap_pp, suggested_trade, etc.) and partition_check details. It also covers edge cases like fill check and placeholder filtering, making the tool fully understandable.

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?

Input schema has 100% coverage with descriptions, but the description adds extensive context: explains modes, provides example slugs, and details the logic for each parameter (e.g., 'walks child markets, checks date-axis/threshold-axis ordering AND computes partition_check').

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 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and contrasts with sibling tools implicitly by focusing on a specific capability.

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 on when to use each parameter: 'Call with NO args for a `trending_scan`... pass `event` for the strongest per-event... or `topic` for a themed cross-event scan.' It also advises against trading when edge is not realizable and suggests polymarket_fill_risk for custom sizing.

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 read-only, open-world, idempotent, non-destructive behavior. The description adds substantial detail: three model families, response structure, caching (1h KV-level), diagnostics for empty segments, tradeable-edge knobs, and edge calculation details (net of slippage, Kelly fractions, 24h-move warnings). 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 lengthy but well-structured with clear grouping of model families and response sections. Each sentence adds value, and the use of number-coded segments helps readability. Could be slightly more concise, but the density is justified by the tool's complexity.

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

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

The description fully explains the return structure (by_segment, fed_candidates/fed_note, _diagnostics), all parameters with rationale, and edge computation details. No output schema exists, so the description carries the full burden and meets it comprehensively.

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 significant value beyond schema: for 'slippage_pp' it explains Polymarket fee structure and suggests adjustments; for 'min_partition_leg_kelly' it clarifies why the general 'min_kelly' filter does not apply; for 'window' it defines the volume window. Every parameter receives extra context.

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 ('Scan top Polymarket markets and return opportunities') and resource (Polymarket markets where Pipeworx data disagrees). It explicitly distinguishes from sibling tools by focusing on disagreement-driven opportunities, and includes a use-case tagline ('what should I bet on today').

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 specifies when to use this tool ('agents discover opportunities without paging hundreds of markets') and provides context for exclusion (Fed bets are surfaced but excluded from ranking). However, it does not explicitly mention alternative tools for different scenarios or when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds operational details: snapshots from daily closes, cache-miss writing, and gaps meaning no scan. 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 fairly long but well-structured with clear sections (args, response, limits). It is front-loaded with the core question. Every sentence provides useful information, though some tightening is possible.

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

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

Given no output schema, the description fully explains the response fields (tracked, expired, snapshot_dates) and their meanings. It covers all parameters, behavioral quirks, and limits, making the tool completely understandable without external reference.

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 descriptions cover 100% of parameters. The description adds defaults, max for days, and explains the response structure (tracked[], expired[], snapshot_dates[]), which goes beyond schema. This adds significant value.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like 'polymarket_edges' by focusing on historical behavior rather than current edges.

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

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

The description implies usage context by contrasting fresh vs. old edges, and specifies limits (60-day TTL, snapshot gaps, no intraday data). It does not explicitly list when not to use, but the context is sufficient for an agent to decide.

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

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

Description reveals behavioral traits beyond annotations: it walks the ladder, returns specific output fields, and warns about forced directional risk and thin legs. It adds value by describing the 'dominant loss mode in real arb-bot P&L', which is not covered by annotations. No contradiction with annotations (readOnlyHint, idempotentHint, 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 well-structured with clear sections (single-market, basket, usage), but somewhat verbose. However, every sentence adds value, and it is front-loaded with the core purpose. Minor deduction for length.

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

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

Despite no output schema, the description lists all return fields for both modes, which is comprehensive. However, some fields lack detailed explanation (e.g., 'verdict' meaning), but it is sufficient for an agent to understand what to expect.

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 significant meaning: interprets size_usd differently for single-market vs basket, explains default side for basket mode, and clarifies required parameters ('REQUIRES one of market or event'). This goes 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 defines the tool as a realizable-vs-theoretical edge check against live CLOB order-book depth, with specific modes (single-market and basket). It uses precise verbs and distinguishes itself from sibling tools like polymarket_arbitrage by explicitly stating when to use this tool before acting on arb signals.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. It explains why (theoretical overround not capturable, partial fills create directional risk), which helps the agent decide when to invoke this tool vs alternatives.

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

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

Annotations indicate readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context: how spreads are computed (raw probabilities, Kalshi minus Polymarket), the safety fields (compatibility_warning, temporal_alignment, skipped counters), and the caveat that premapped does not imply tradeable. No contradictions with annotations.

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

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

The description is relatively long but well-organized: purpose, modes, response details, safety fields, caveats. Each sentence serves a purpose. Could be slightly more concise, but the structure aids 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?

Without an output schema, the description fully explains the response structure (per-venue prices, spreads, safety fields). It covers parameter combinations, edge cases (compatibility_warning scenarios, temporal alignment), and the limitation of premapped topics. Complete for a complex tool.

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

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

Schema coverage is 100% with descriptions for each parameter. The description adds value by listing the exact topic enum values, explaining the override behavior for explicit tickers, and providing example usage. This goes beyond the schema alone.

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

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

The description clearly states the tool computes a cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from sibling tools like polymarket_arbitrage by focusing on two-venue comparison and explains two distinct modes (topic shortcuts and explicit pairing).

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

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

The description specifies when to use topic mode vs explicit mode, and explains when the compatibility_warning indicates non-tradeable spreads. It does not explicitly contrast with sibling tools but provides strong usage context. The warning that most premapped topics return warnings is helpful for setting expectations.

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 safe, idempotent behavior. The description adds value by detailing the return structure (reference, full text, translation ID, breakdown), which goes beyond annotations.

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

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

Two sentences, front-loaded with purpose. 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 zero parameters and existence of output schema, the description fully explains what the tool returns and its scope.

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?

No parameters, schema coverage 100%. Baseline of 4 is appropriate since no parameter descriptions needed.

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

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

The description clearly states the action ('Fetch') and resource ('random Bible verse') and specifies the translation (WEB), distinguishing it from siblings like get_verse that fetch specific verses.

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 random retrieval but does not explicitly state when to use this over sibling tools like get_verse or get_passage.

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 and idempotentHint. Description adds critical behavioral context: scoping to user identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys by omitting the key argument. 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 concise sentences, each adding value. Front-loaded with the main action. No unnecessary words or repetition.

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

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

Given the tool's simplicity and the absence of an output schema, the description sufficiently explains both behaviors (retrieve by key, list all keys) and scoping. No gaps identified.

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

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

Schema coverage is 100% and description adds meaning by explaining the effect of omitting the key (list all keys) and providing examples of usage (user's target ticker, address, research notes). This goes beyond the schema's parameter 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?

Description clearly states the verb 'Retrieve' and resource 'value previously saved via remember', and distinguishes from sibling tools 'remember' and 'forget' by pairing them. It also explains the alternative behavior of listing all keys when the key argument is omitted.

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: 'to look up context the agent stored earlier... without re-deriving it from scratch' and provides context about scoping. It pairs with 'remember' and 'forget' for related actions, giving clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral details: each alert carries source, citation_uri, raw payload; mark_read affects subsequent calls; polling works; same data via REST endpoint. No contradictions.

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

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

Single well-structured paragraph, front-loaded with purpose, no redundant sentences, 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?

Despite no output schema, description covers output fields, filtering, mark_read behavior, and references an alternative endpoint. Missing some details on unread_only and exact response format, but overall adequate for a read-only feed tool with good annotations.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining the effect of mark_read and giving an example for type filter ('sec_8k'). Not all parameters are explicitly described (e.g., unread_only, limit), but the key ones get extra context.

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

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

The description clearly states the verb 'Pull' and the resource 'fired events from your subscription feed', distinguishing it from sibling tools like list_subscriptions, 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 clear context: filtering by type and since, use of mark_read, and mentions polling works and an alternative endpoint for scripts/dashboards. Lacks explicit when-not-to-use guidance but context is strong.

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

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

The description goes beyond annotations by detailing the tool's multi-source fan-out behavior (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail), return format (changes grouped by source, total_changes count, citation URIs), and failure handling. This aligns with the readOnlyHint, openWorldHint, and idempotentHint 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 a single efficient paragraph that front-loads example queries, then explains functionality, sources, parameters, and alternatives. While slightly dense, every sentence contributes. It could be broken into shorter sentences for easier scanning, but it is concise overall.

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 absence of an output schema, the description adequately explains the return structure (changes grouped by source, total count, citation URIs). It covers all parameters, mentions failure modes (USPTO soft-fail, GDELT→GNews fallback), and provides an alternative tool (entity_profile). This makes it fully self-contained for an agent.

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

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

The input schema already describes all three parameters (100% coverage). The description adds value by explaining `since` accepts both ISO dates and relative shorthand, and provides recommended defaults. It also clarifies that `type` is currently limited to 'company', which supplements the enum.

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: retrieving a change feed for a company (filings, news, patents) in one parallel call. It provides example queries ('what's new with X') and distinguishes from the sibling tool entity_profile, which serves static profile data.

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

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

The description gives explicit guidance on when to use this tool (e.g., 'latest on Y', 'updates on Acme') and when not to (use entity_profile for static profile). It also explains parameter usage, including the `since` parameter format. However, it could be more thorough about when not to use it (e.g., for non-company entities).

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 idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds behavioral context beyond annotations: 'Stored as a key-value pair scoped by your identifier. Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours.' This discloses persistence behavior and scoping, which is valuable for the agent's decision-making.

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. It starts with the core action, then provides usage guidance, then scoping and persistence details, and finally pairing with other tools. No redundant or extraneous information. It is well-structured and front-loaded.

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

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

Given the tool is a simple key-value store with no output schema, the description covers all necessary context: what it does, when to use it, how data is stored (key-value, scoped), persistence duration, and pairing with recall/forget. It is complete for an agent to make informed decisions.

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

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

Schema covers both parameters with descriptions (100% coverage). The description adds value by providing example keys in the key schema description (e.g., 'subject_property', 'target_ticker') and clarifying the value as 'any text'. While the schema already describes the semantics adequately, the examples in the schema description (part of the input schema) enhance understanding, and the tool description reinforces the key-value pair concept.

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 specifies the verb 'save' and the resource 'data', making the action and object unambiguous. The mention of cross-session reuse distinguishes it from simple conversation storage, and the context of 'discovering something worth carrying forward' provides clear intention.

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

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

The description explicitly states when to use the tool: 'when you discover something worth carrying forward... so you don't have to look it up again.' It also provides usage context by describing pairing with recall and forget, which are sibling tools. This gives clear guidance on when to invoke and when to use alternatives.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds that each call cascades through several internal endpoints, which provides context beyond annotations. It does not contradict annotations. No error handling or ambiguity resolution details are mentioned, but the annotations cover safety.

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

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

The description is a single, well-structured paragraph that front-loads key examples and usage guidance. Every sentence adds information without unnecessary repetition, making it efficient and easy to parse.

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 moderate complexity (two types, internal cascading), the description covers what it returns and when to use it. It mentions auto-disambiguation for company inputs. However, it lacks details on error handling or cases where resolution fails, which could be helpful but is mitigated by idempotent and read-only annotations.

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

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

Schema coverage is 100% with descriptions for both parameters. The description adds significant value by detailing the return values for each type (ticker+CIK+company_name for company; RxCUI+ingredient+brand for drug) and providing examples for the value parameter (e.g., 'AAPL', 'ozempic'). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool resolves names to identifiers, with specific examples like 'ticker for...' and 'CIK for...'. It mentions the supported types (company, drug) and the outputs. However, it does not explicitly differentiate from sibling tools like entity_profile or compare_entities, which handle related but different tasks.

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 advises 'Use FIRST whenever you have a name but need an ID', providing explicit guidance on when to use the tool. It also notes that it replaces 2-3 manual lookups, implying efficiency. However, it does not discuss when not to use it or list 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 cover readOnly, idempotent, non-destructive. Description adds that it probes each entity with ai_visibility_check, ranks by score, and returns ranked list 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?

Four sentences, each purposeful: defines action, explains method, gives use case, describes output. No redundancy or filler.

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

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

Despite no output schema, description specifies return fields (score, confidence, signal density per entity). With good annotations and schema coverage, description is complete for this moderate-complexity 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%, so parameters are well-documented. Description adds context that first entity is the 'subject' and models default to workers-ai, but doesn't significantly augment 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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and ranks results. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (generic comparison).

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

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

Description gives a concrete use case: competitive AI-marketing audits, with an example question. It implicitly contrasts with ai_visibility_check but does not explicitly list when not to use or alternative tools.

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

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

Annotations already mark it as readOnly, idempotent, not destructive. Description adds rich behavioral details: returns summary block, per-advisory detail, links, alternative versions, and notes partial failures with bundlephobia timing (5-30s) and that sources_failed will list timeouts. 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 dense but every sentence adds value. Front-loaded with purpose, then use case, return summary, ecosystem note, and partial failure behavior. Well-structured with 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?

Despite no output schema, the description comprehensively explains return values (summary block fields, per-advisory detail, links, alternative versions) and behavior under partial failure. For a tool with only two simple parameters, this is complete.

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

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

Schema coverage is 100% but description adds value by explicitly noting scoped packages are accepted (e.g. '@types/node') and version defaults to latest. This provides additional clarity 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 defines the tool as a composite check for evaluating npm packages, fanning out to deps.dev and bundlephobia. It uses specific verb+resource ('scan'/'check' + 'npm package') and distinguishes from sibling tools by its unique purpose among a diverse set of 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 states when to use: 'whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me''. Also provides exclusion: NPM ecosystem only in v1, other ecosystems fall under deps.dev:version directly.

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

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

Adds significant detail beyond annotations: 'BGE-base-en embeddings + cosine over 500-char overlapping windows; cap is 200K chars (longer inputs are truncated and flagged)' and mentions that every passage carries an offset for verification. Annotations already provide readOnlyHint etc., but description enriches with technical and behavioral specifics.

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

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

Approximately four sentences, each contributing uniquely: purpose, usage context, pairing advice, technical details. No redundant words; front-loaded with core action.

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

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

Despite no output schema, the description explains return shape: 'top-N passages with character offsets and similarity scores'. Combined with parameter coverage and usage guidelines, the description is fully complete for this 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% with descriptions for all three parameters. The description adds value by explaining the purpose of 'text' (document text), giving example queries for 'query', and clarifying the range of 'limit'. This justifies a score above 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 'Semantic search INSIDE a fetched record', specifying the verb 'search within' and the resource 'a fetched record'. It distinguishes from sibling tools by mentioning pair usage with ask_pipeworx_grounded, indicating a specific niche.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and describes pairing with ask_pipeworx_grounded. However, it does not explicitly state when NOT to use or list alternative tools beyond that pair.

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 implies each call creates a new subscription (non-idempotent), but the annotation says 'idempotentHint: true'. This is a direct contradiction. The description does add useful behavioral context (auth requirements, rate limits, delivery constraints), but the contradiction severely undermines 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 somewhat long but well-structured, starting with purpose, then requirements, then types with examples, then delivery options. Every sentence adds value, though some users might prefer a shorter version.

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 types, nested objects, delivery channels) and the absence of an output schema, the description covers key aspects: auth, type-specific parameters, delivery constraints, and rate limits. Missing details on error handling prevent a perfect score.

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 description adds significant meaning beyond the schema, with detailed explanations for each subscription type and delivery channel, including examples and constraints. The schema coverage is 100%, so the baseline is 3, but the added detail earns a 4.

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

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

The description clearly states the action ('Create a proactive monitoring subscription'), the resource ('live-data event stream'), and the return value ('Returns the new subscription id'). It differentiates from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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

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

The description provides clear context for when to use the tool (creating a subscription) and includes prerequisites (requires Pipeworx OAuth account). However, it does not explicitly mention when not to use it or point to alternative tools for other operations.

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

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

Adds context beyond annotations: describes output as example questions with tool shapes, explains behavior with/without topic, and mentions live catalog. Annotations already cover safety; description enriches understanding.

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

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

Front-loaded with example intents, well-structured, each sentence adds value. Slightly verbose but efficient given complexity.

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

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

Thoroughly covers purpose, usage, parameters, and integration with other tools. No output schema, but description adequately describes return type.

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

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

Schema covers topic with description, but description adds explicit list of focus areas and explains behavior when omitted, providing meaning beyond schema coverage.

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 an onboarding entry point that returns category-bucketed example questions with tool+argument shapes, distinguishing it from sibling tools like ask_pipeworx. It uses specific verbs and resources.

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' and mentions alternatives like ask_pipeworx, entity_profile, etc. Provides clear when-to-use guidance.

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

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

Beyond annotations (idempotent, not destructive), the description adds key behaviors: ownership enforcement prevents canceling others' subscriptions, and deactivation preserves historical events. This provides context annotations alone cannot convey.

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

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

Two sentences deliver complete information: main action, ownership constraint, and behavioral consequence. No unnecessary words; front-loaded with the core purpose.

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

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

For a simple tool with one parameter and no output schema, the description covers ownership, deactivation (not deletion), and linkage to 'recent_alerts'. Annotations already provide idempotency and non-destructive hints, making this complete.

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

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

Schema has 100% coverage with a clear description for the single parameter 'id'. The tool description does not add additional meaning beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the action (cancel/unsubscribe) and resource (subscription by id). It distinguishes itself from siblings like 'subscribe' and 'list_subscriptions' by specifying ownership enforcement and deactivation semantics.

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 tells when to use (to cancel a subscription, ownership enforced) and hints at when not to use (if full deletion is needed, use another tool). It also references 'recent_alerts' for historical events, providing guidance on related tools.

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

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

The description adds significant behavioral context beyond the annotations: it names the data sources (SEC EDGAR + XBRL), lists the possible verdicts, mentions the citation format, and explains that it replaces multiple 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 moderately long but well-structured, starting with usage patterns, then domain, then output details. Every sentence adds value, though it could be slightly more concise without losing clarity.

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 required parameter, no output schema), the description provides sufficient context: input examples, domain limitation, and expected outputs. It lacks details on error handling or edge cases, but overall completeness is good.

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

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

Schema coverage is 100% for the single 'claim' parameter, and the schema describes it. The description adds value by giving natural-language examples and clarifying what constitutes a valid claim, thus enhancing understanding beyond the schema alone.

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

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

The description clearly identifies the tool as claim verification against authoritative sources, provides example queries, and explains it returns a verdict. The purpose is specific and well-defined, though it does not explicitly distinguish from sibling tools. However, the verb+resource+scope is exceptionally clear.

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

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

The description states when to use the tool (whenever the agent needs to fact-check claims) and specifies the domain (company-financial claims). It implies a limitation (US public companies, v1) but does not explicitly state when NOT to use it or mention alternatives among siblings.

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