Hagstofa Is

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

Annotations already declare readOnlyHint=true, idempotentHint=true, etc., but the description adds significant value: it explains the default LLM (free Workers AI), the need for a BYO API key for Anthropic (and cost implications), the return structure (per-model score, confidence, signals, raw_response + combined view), and the scoring scale (0-100). This goes well beyond annotations, making agent decisions safe and informed.

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

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

Four sentences with zero wasted words. First sentence states the core action and output. Second explains default vs. paid models. Third details return format. Fourth lists use cases. Information is front-loaded and every sentence earns its place. Perfect conciseness.

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

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

Given 4 parameters (all described), rich annotations, and no output schema, the description compensates by detailing the return structure. It covers prerequisites (_apiKey for Anthropic), default behavior, and use cases. No missing information is critical for correct invocation. The tool is fully described for an agent to use without additional context.

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

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

Schema coverage is 100%, so baseline is 3, but the description enhances understanding: it explains that 'entity' is the subject to probe, that 'models' defaults to Workers AI but can include Anthropic with _apiKey, that _apiKey is passed directly to Anthropic (not stored), and that 'context' disambiguates entities. This adds practical, operational meaning beyond the schema descriptions.

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

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

The description clearly states the tool probes LLMs to score visibility of an entity (business/brand/product/topic) per model, with a specific score range (0-100). This uniquely distinguishes it from sibling tools like 'ask_pipeworx' (simple Q&A) and 'scan_competitor_ai_presence' (competitor-specific scan), establishing a clear, non-overlapping 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?

The description provides explicit usage scenarios: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' While it doesn't name specific alternatives or when NOT to use it, these use cases give strong contextual guidance. A minor gap is the lack of direct comparison to siblings like 'compare_entities' or 'scan_competitor_ai_presence', but the examples suffice for most agents.

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 reveals that the tool routes questions to one of 3,804 tools across 907 sources, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. This aligns with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) and provides concrete behavior that helps the agent understand what happens when invoked. No contradiction exists.

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 key message 'PREFER OVER WEB SEARCH' and is well-structured with examples and use cases. It is somewhat lengthy but every sentence earns its place by providing actionable guidance. It could be slightly trimmed, but the level of detail is appropriate for a complex tool with many possible queries.

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 (routes to many sources) and the lack of an output schema, the description provides sufficient context: it explains the tool's behavior, how it handles queries, and what the output looks like (structured answer with citations). It could be more explicit about the exact return format, but for a question-answering tool, it is complete enough.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description does not add new parameter semantics beyond what is in the schema; it merely states the tool accepts a natural language question and lists aliases. The examples in the schema provide typical use, but the description does not elaborate on parameter format or constraints. This is adequate but not exceptional.

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 purpose: answering factual questions about current/historical data from authoritative sources with citations. It uses specific verbs like 'answers', 'routes', and 'returns', and distinguishes itself from web search by positioning itself as preferred. It also distinguishes from siblings like 'ask_pipeworx_grounded' by implication (the main tool is the general one), but the explicit preference over web search and the mention of 3,804 tools and 907 sources sets it apart.

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 'PREFER OVER WEB SEARCH' and provides a wide range of example use cases (SEC filings, FDA data, etc.) and linguistic cues (e.g., 'what is', 'look up'). It clearly indicates when to use this tool. However, it does not explicitly mention when not to use it (e.g., for subjective questions, or when the user needs to filter by specific tool), which would make it a 5. Still, it is highly informative and actionable.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds that the tool is 'hallucination-resistant', uses only tool result, returns explicit refusal reasons, and costs an extra LLM call. 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?

Highly concise and front-loaded with the key phrase. Every sentence adds unique information: purpose, mechanism, return format, use cases, trade-off. 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?

Despite no output schema, the description fully specifies the return structure with answer, evidence, confidence, source, fetched_at, and refusal reasons. Covers all important aspects for a high-stakes read 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 all parameters. The description adds minimal additional meaning beyond what the schema provides, but it contextualizes the question parameter's role in the grounded pipeline.

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: 'Hallucination-resistant answer mode for high-stakes reads.' It specifies it extracts answers using only tool results and distinguishes itself from sibling 'ask_pipeworx' by adding an extra LLM call for groundedness.

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 provides exclusions: 'prefer ask_pipeworx for casual lookups.' Also mentions cost trade-off.

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

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

Beyond annotations, the description details classification, fan-out, response shapes, resolver contract, parent event extraction, news fallbacks, safety mechanisms, and resolution-rule risk. Highly transparent with no contradictions.

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

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

Description is very long and dense, though structured with sections. Could be more concise; some details could be streamlined 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?

Extremely complete: covers input, processing, output, error modes, edge cases, and fan-out examples for various bet types. No gaps despite no output schema.

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

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

Schema coverage is 100%, and the description adds significant context: market parameter flexibility (slug/URL/question), depth enum explanation, include_raw implications, and examples. Enhances understanding beyond schema.

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

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

The description clearly states the tool's purpose: research a Polymarket bet by pulling Pipeworx data. It specifies input types, processing steps, and output structure, making the purpose unambiguous.

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

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

Explicit usage examples are given (e.g., 'should I bet on X'). Context for when to inspect specific fields is provided, but no explicit exclusion of sibling tools or when-not-to-use.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false, so the description doesn't need to repeat those. It adds valuable context: for companies, it pulls 10-K data with off-calendar fiscal year handling; for drugs, it pulls FAERS adverse events and FDA approvals. It also mentions sorting by primary metric and returns citation URIs.

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

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

The description is two sentences with excellent front-loading: it starts with example natural language triggers, then defines core functionality. No redundant information. Every sentence earns its place, covering purpose, usage, data sources, and return format efficiently.

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

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

Given the tool's complexity (two entity types, different data sources, sorting, citations), the description is fully complete. It explains what data is pulled for each type, how results are sorted, and that citations are provided. No output schema exists, but the description adequately covers 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% with clear descriptions for both parameters. The description adds meaning beyond the schema: it explains what type='company' returns (revenue, net income, cash, debt) and type='drug' returns (adverse events, approval counts, trial counts), and how values should be formatted (tickers/CIKs for companies, drug names). Max/min items are reiterated.

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

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

The description uses specific verbs and resources ('side-by-side comparison of 2–5 companies or drugs') and clearly distinguishes from sibling tools like entity_profile (single entity) and ask_pipeworx (general Q&A). It provides example natural language triggers and explicitly states 'ALWAYS PREFER over sequential single-pack 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?

The description gives explicit guidance: it states when to use this tool ('ALWAYS PREFER...') and provides example queries. It also explains what each type parameter does, helping the agent decide between company vs drug comparisons. No explicit when-not, but the preference statement is strong 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 provide safety profile (readOnlyHint, etc.). Description adds rich behavioral details: verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[] array, no invention, structured findings packet. No contradiction.

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

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

Three sentences front-load key info (what, how, when). Every sentence earns its place, though slightly verbose on sources count (3,804 tools, 907 sources).

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 fully explains return format (findings packet with citations, gaps, etc.). Covers decomposition, parallelism, account requirement, and paid plan limitation.

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 depth enum values correspond to number of facets (quick=3, standard=5, thorough=8) and that thorough requires paid plan.

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

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

Description uses specific verb 'research' with resource scope 'multi-source' and explicitly contrasts with sibling ask_pipeworx. Clearly states it decomposes questions, routes to tools in parallel, and returns structured findings.

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 use cases: 'Use for broad or multi-part questions' and 'use ask_pipeworx for single lookups'. Also mentions account requirement and paid plan for depth:thorough.

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 safety (readOnlyHint, idempotentHint, destructiveHint false). Description adds that results include full schemas and are ready to call directly, no second lookup needed. Adds behavioral context beyond annotations.

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

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

Description is a single paragraph but well-structured: purpose, examples, return value, guidance. Efficient use of words; could be slightly tighter but still effective.

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

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

No output schema, so description explains return values (names, descriptions, full schemas). Covers aliases and examples. Annotations cover safety. Complete given the tool's complexity.

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

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

Schema coverage is 100% (baseline 3). Description adds examples, explains aliases, and clarifies that the main parameter is a natural language query. Provides meaning beyond schema descriptions.

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

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

The description clearly states the tool finds tools based on a description of the data or task, lists many example domains, and explicitly distinguishes itself from siblings by advising to call it first to see the option set.

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 when to use: '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).' Provides clear context.

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

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

Annotations already indicate read-only, non-destructive, open-world behavior. The description adds valuable behavioral context: it fans out across multiple sources (SEC EDGAR, XBRL, USPTO, news, GLEIF), mentions soft-fail for patents (USPTO API sunset), and details return fields. No contradiction with annotations.

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

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

The description is a single dense paragraph but is well-structured with examples, usage guidance, and return details. It is concise but packs significant information. Could be slightly more structured (e.g., bullet points for return fields), but it remains efficient 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?

Despite no output schema, the description comprehensively details return fields (cik, filings, fundamentals, patents, news, LEI) and explains limitations (names not supported, patents soft-fail). For a 2-param tool with 100% schema coverage, this is complete and sufficient.

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

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

Schema coverage is 100%, with both 'type' and 'value' described. The description repeats and slightly extends this (e.g., 'zero-padded CIK'), but adds minimal new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description explicitly states the tool's purpose: providing a full cross-source profile of US public companies. It lists example queries ('Tell me about X', 'research Acme') and distinguishes from sibling tools like resolve_entity by specifying that names are not supported.

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

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

The description clearly states when to use this tool: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also provides an alternative: 'use resolve_entity first if you only have a name.' This gives explicit usage 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 provide destructiveHint=true and idempotentHint=true. The description adds context about clearing sensitive data, which is useful but does not add significant behavioral detail beyond what annotations indicate.

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

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

Two sentences, no wasted words. Front-loaded with action, then usage context.

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

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

For a simple tool with one parameter and no output schema, the description fully covers purpose, usage, and behavioral context. Paired with good annotations, it 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% with a clear description for the only parameter 'key'. The description does not add additional meaning beyond the schema.

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

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

The description clearly states the action 'Delete' and the resource 'a previously stored memory by key'. It also distinguishes from sibling tools 'remember' and 'recall' by mentioning pairing.

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

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

Explicitly gives when to use: 'context is stale, task is done, or clear sensitive data'. Also suggests pairing with remember and recall, providing clear alternatives.

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

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

The description adds value beyond annotations by detailing the process: fetches the page, extracts title/description/key links, emits standard markdown. No contradictions 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 a single well-structured paragraph that fronts the purpose and follows with details. It is concise, with every sentence contributing meaningful information.

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

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

Given the low complexity (2 parameters, no output schema), the description is fully complete. It explains input, process, output format, and multiple use cases, leaving no gaps for an AI agent.

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

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

With 100% schema coverage, the baseline is 3. The description adds no new semantic details beyond the schema, but it does hint at the output format ('standard llms.txt markdown format'), which is a minor addition.

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

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

The description specifies a clear verb ('generate'), a specific resource ('production-ready llms.txt file'), and a target audience ('AI crawlers'). It distinguishes from siblings by focusing on llms.txt generation, a unique purpose among the listed tools.

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

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

The description provides explicit use cases: indexing a client's site, drafting for own project, auditing competitors. While it doesn't state when not to use, the given scenarios are clear and helpful for an AI agent.

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 readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds return fields and default filtering (active subscriptions), but doesn't significantly expand 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, directly front-loaded with purpose, no redundant 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?

Lists return fields and parameter behavior. Lacks mention of pagination or limits, but adequate for a simple list tool.

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

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

Schema coverage is 100% with description for 'include_inactive'. Description does not add additional parameter information beyond what the schema provides.

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

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

The description clearly states 'List the caller's active subscriptions' with specific return fields, distinguishing it from sibling tools '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?

It provides explicit use cases: 'review what you're monitoring before adding more or to find an id to cancel'. Lacks explicit when-not to use, but context is clear.

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

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

The description discloses key behavioral traits: rate-limited to 5 per identifier per day, free, and doesn't count against tool-call quota. Annotations are all false, and the description adds necessary context about mutation (submitting feedback) without contradicting annotations.

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

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

The description is concise (5 sentences) and well-structured: it starts with the core purpose, then breaks down use cases, provides anti-pattern guidance, and ends with constraints. 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?

The description covers all essential aspects: use cases, parameter usage, rate limits, quota impact, and expected message style. No output schema exists, so return values are not needed. It is complete for a feedback submission tool.

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

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

Schema description coverage is 100%, but the description adds value beyond schema details: it clarifies the meaning of each enum value, explains the context field's optionality and relation to pack/tool/vertical, and advises on message content (be specific, 1-2 sentences, 2000 char max).

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates specific feedback types (bug, feature, data_gap, praise) and distinguishes itself from sibling tools like ask_pipeworx by focusing on feedback rather than queries.

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

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

The description provides explicit guidance on when to use each feedback type: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also advises against pasting end-user prompts, offering clear usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds that data is self-aggregating, no PII, and cached 5min-1h. Provides meaningful 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?

Three sentences: purpose, use cases, technical notes. Front-loaded, no filler. Every sentence adds value.

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

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

With only one optional parameter and no output schema, the description fully covers behavior, caching, privacy, and usage scenarios. No gaps.

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

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

Schema coverage 100%, but description adds nuance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This enhances understanding beyond 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?

Clearly states it returns top tools, top packs, and total call volume over a window. Verb 'returns' with specific resources. Distinguishes from siblings like discover_tools and ask_pipeworx by focusing on trending usage 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?

Lists three explicit use cases (discovering hot sources, confirming canonical tool, aligning use case). Does not explicitly state when not to use, but context is clear given sibling list. Window guidance provided.

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 non-destructive, so the description's behavioral details add value: it explains the requirement for one of event/topic, fill check logic, Jaccard similarity threshold, and partition filter. No contradiction with annotations.

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

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

The description is long but well-structured with clear sections (REQUIRES, event, topic, SEMANTIC ANCHOR, etc.). It front-loads the key requirement. Slight verbosity but earned.

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

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

Given the complexity (two modes, multiple checks) and no output schema, the description fully covers behavior, output structure, and fills gaps. It also references related tools, 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% with adequate parameter descriptions. The description adds context (examples, mode explanations) but does not significantly enhance parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, making the purpose unambiguous and differentiating it from siblings like polymarket_edges.

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

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

Explicitly recommends when to use `event` vs `topic`, states that calling with no args fails, and references `polymarket_fill_risk` for custom sizing. This provides clear guidance on alternatives and usage context.

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

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

Annotations already indicate readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds extensive behavioral details beyond annotations: cached at KV level for 1 hour, response structure with segments and diagnostics, specific model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation (net of slippage, with 24h-move warning), tradeable-edge knobs, and placeholder-slug filter. No contradictions with annotations.

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

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

The description is very long (multiple paragraphs) and dense with technical details (e.g., specific alphas, placeholder slug patterns, cache timing). While it is well-structured with clear sections, it could be more concise for efficient agent parsing. The first sentence provides a summary, but subsequent details may overwhelm.

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

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

Given the tool's complexity (9 parameters, no output schema, nested response structure with diagnostics), the description is exceptionally complete. It explains the response structure (by_segment with three segments, fed_candidates, diagnostics), why certain segments may be empty, and the logic behind model families and filters. This ensures agents fully understand inputs and outputs without needing an output schema.

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

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

Schema description coverage is 100% with 9 parameters, so baseline is 3. The description adds semantic value by explaining how parameters like min_liquidity and max_spread_pp act as 'tradeable-edge filters' and clarifying that min_kelly applies to single-leg opportunities while min_partition_leg_kelly applies to partition legs. This context helps agents choose parameters effectively, moving it above baseline.

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

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

Clearly states 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' Provides a specific verb ('scan'), resource ('Polymarket markets'), and explicitly distinguishes the purpose from generic market scanning by framing it for daily betting discovery. The description of three response segments and tradeable-edge knobs further clarifies what the tool does.

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

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

Explicitly says 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' This gives clear usage context. However, it does not explicitly state when NOT to use this tool versus siblings like polymarket_arbitrage or bet_research, so guidance on alternatives is implicit rather than explicit.

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 well beyond annotations by detailing response structure (tracked, expired, snapshot_dates), behavioral traits (trend types, decay computation, lifespan), and limitations (60-day TTL, daily closes). No contradiction with annotations.

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

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

The description is well-structured with a clear front-loaded purpose, then args, then response. It is somewhat verbose but necessary given the tool's complexity. Every sentence adds value.

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

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

Given no output schema, the description thoroughly explains return values and limitations. It assumes knowledge of polymarket_edges concepts, but covers all critical aspects for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context (e.g., max 30 days, snapshot family) but does not significantly extend meaning beyond schema descriptions.

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

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

The description clearly states the tool's purpose: tracking edge persistence and decay from daily snapshots. It distinguishes from sibling tools like polymarket_edges by focusing on historical telemetry and decay analysis 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 (e.g., distinguishing fresh wide edges from old ones) but does not explicitly contrast with alternatives or state when not to use it. It provides enough guidance for an AI agent to understand applicability.

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

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

The description adds significant behavioral context beyond the annotations: it explains that the tool walks the ladder, returns a verdict (clean|degraded|cannot_fill), and highlights forced directional risk. It does not contradict any annotations; the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false) are consistent with the description.

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

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

The description is appropriately sized and well-structured with clear sections (overview, single-market, basket, usage guidance). Every sentence adds value, and the key information is front-loaded. No redundant or vague statements.

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 lack of an output schema, the description thoroughly covers return values for both modes, including top-of-book, VWAP fill price, slippage, shares filled, verdict, and per-leg details. It also explains the risk of partial fills and forced directional risk, making the tool's behavior 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?

Schema description coverage is 100%, and the description adds further meaning: for 'side', it explains the default behavior for basket mode (auto based on partition sum); for 'size_usd', it clarifies interpretation per mode (spend vs target proceeds vs settlement notional) and provides clamp values. 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, distinguishes between single-market and basket modes, and lists specific return fields. It differentiates from sibling tools by explicitly stating when to use it before acting on arbitrage signals or large trades.

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

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

The description provides explicit usage guidance: use this tool 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 on thin books, partial basket fills convert arb into unhedged directional position) and states the requirement for either 'market' or 'event' parameter.

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 fully discloses behavioral traits beyond annotations: two modes, response structure with safety fields like compatibility_warning and temporal_alignment, and counters for dropped comparisons. It explains the meaning of compatibility_warning in two cases. 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 verbose (200+ words) but well-structured: purpose first, then modes, response, safety fields. It could be more concise by trimming redundant warnings, but it remains readable.

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

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

With no output schema, the description explains the response structure (leg-by-leg prices, spread, safety fields) and covers edge cases (compatibility_warning, temporal_alignment). It lacks a formal example but is sufficient for understanding.

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

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

Schema coverage is 100%, baseline 3. The description adds value by explaining the two modes (topic vs explicit), providing examples for topic, and stating that explicit parameters override topic-mapped sides. This helps the agent understand parameter relationships.

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 computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes itself from related sibling tools like polymarket_arbitrage by focusing on cross-venue comparison.

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

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

The description explains when to use the tool (to find cross-venue spreads) and when not to (when compatibility_warning fires). It provides context about the two modes and notes that real spreads are rarer than the shortcut list suggests, but does not explicitly name alternatives.

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

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

Annotations already declare readOnly, openWorld, and idempotent hints. The description adds important behavioral context: that the tool interacts with a rate-limited external API (PxWeb) and that the path must include the '.px' suffix, which is beyond annotation information.

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

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

The description is extremely concise: two sentences, no wasted words, front-loaded with the core purpose followed by key constraints.

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

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

While the description conveys core purpose and a usage constraint, it lacks explanation of the return value (no output schema). The response format 'json-stat2' is only mentioned in the input schema's body description, not in the tool description. For a tool pulling data, this is a notable gap.

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 50% with the path parameter lacking description in schema. The description adds that path includes '.px suffix', which is a critical clue. For the body parameter, the schema already describes its structure, so the description's mention of 'PxWeb query object' adds minimal new information. Overall, it partially compensates for the missing 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 the verb ('Pull data') and the resource ('a table'), including the specific '.px' suffix requirement for the path. It distinguishes itself from siblings like 'table_meta' which likely handles metadata.

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 advises to filter dimensions to keep cell count small due to PxWeb request size limits, providing actionable usage guidance. However, it doesn't mention when to use alternatives or when not to use.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context about scoping (anonymous IP, BYO key hash, account ID) and the relationship to 'remember' and 'forget', which helps the agent understand broader context. No contradictions.

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

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

Three sentences, each serving a distinct purpose: main action, use cases, and scope/related tools. No redundant information. Front-loaded with the primary function.

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

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

For a tool with one optional parameter and no output schema, the description fully covers what the tool does, when to use it, and how it relates to other tools. It provides sufficient context for correct invocation.

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

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

The description adds meaning beyond the schema: it explains that omitting the key lists all saved keys, and it provides examples of what keys might contain. Schema coverage is 100%, but the description enhances understanding of the parameter's purpose.

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

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

The description clearly states that it retrieves a value previously saved via 'remember', or lists all keys if no key argument is provided. It gives concrete use cases (ticker, address, notes) and distinguishes itself from sibling tools 'remember' and 'forget'.

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

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

The description explicitly says when to use: to look up context the agent stored earlier without re-deriving it. It also mentions pairing with 'remember' and 'forget', but does not explicitly exclude scenarios where alternative tools might be better. However, the guidance is clear enough for most cases.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral details: setting mark_read:true flags events as read, affecting future calls, and explicitly states polling is safe. 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 extremely concise with no wasted words. The first sentence immediately states the purpose, followed by essential details on return fields, filtering, and side-effect (mark_read). It front-loads the most critical information and earns each sentence.

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 5 parameters (all with schema descriptions) and no output schema, the description compensates by describing return fields and offering context about polling and alternative access. It covers the tool's functionality well, though it could mention the 'limit' parameter for completeness (though schema covers it). Overall, it is complete enough for effective use.

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

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

Schema coverage is 100%, so each parameter already has a clear description. The description reinforces the 'type' and 'since' parameters with examples but does not add new meaning beyond the schema. It mentions return fields but not parameter details. Baseline score of 3 is appropriate.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed, specifies the return fields (source, citation_uri, raw payload), and distinguishes it from sibling tools like 'recent_changes' by focusing on alerts. The verb 'Pull' and resource 'fired events from your subscription feed' are specific and unambiguous.

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

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

The description provides clear context for when to use the tool (to retrieve recent alerts) and mentions an alternative method for scripts/dashboards (direct API access), but does not explicitly state when not to use it or how it compares to siblings like 'list_subscriptions' or 'recent_changes'. The guidance is adequate but could be more explicit about 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?

The description discloses behavior beyond annotations: it fans out to three sources, uses GDELT preferred with GNews fallback on rate limits or 5xx, notes USPTO PatentsView API sunset, and describes the return structure (changes grouped by source, total_changes count, citation URIs). This adds substantial context to the read-only, idempotent, open-world annotations.

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

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

The description is well-structured with examples at the start, logical progression of sources, and a clear alternative recommendation. However, it is somewhat verbose (e.g., including the USPTO sunset date detail). Still, every sentence adds value, and it remains readable.

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 fully explains the return format (changes[], total_changes, citation URIs). It covers all three data sources, fallback logic, parameter options, and points to the sibling tool for static needs. This is complete given the tool's complexity.

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

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

Schema coverage is 100% with parameter descriptions, but the description adds value by explaining the `since` parameter's relative shorthand ('7d', '3m', etc.) and recommending '30d' or '1m' for typical monitoring. It also clarifies that `value` accepts ticker or zero-padded CIK. This goes beyond the schema's minimal descriptions.

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

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

The description clearly states the tool returns recent changes for a company across SEC filings, news (GDELT/GNews), and patents within a specified time window. It provides example queries ('What's new with X') and distinguishes itself from the sibling tool entity_profile, which returns 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 explicitly explains when to use this tool (for change feed over a window) and when not to (use entity_profile for static profile). It also details fallback behavior (GDELT to GNews) and the USPTO soft-fail condition, guiding effective invocation.

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

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

Description adds context beyond annotations: key-value pair storage, scoped by identifier, persistence details (auth users vs 24hrs anonymous). Annotations already indicate idempotentHint=true, destructiveHint=false, and description is consistent.

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

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

Four sentences, each serving a purpose: purpose, usage scenario, storage details, and pairing. Front-loaded with main 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?

Given the tool's simplicity (2 required string params, no output schema), the description covers all relevant aspects: what, when, how, scope, and lifecycle. No gaps.

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

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

Schema coverage is 100% with good descriptions for key and value. Description adds context about key usage patterns ('subject_property', 'target_ticker') and clarifies value can be any text. Adds moderate value beyond schema.

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

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

The description clearly states the tool saves data for reuse, gives specific examples (resolved ticker, target address), and distinguishes from sibling tools recall and forget.

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

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

It explicitly says 'Use when you discover something worth carrying forward', explains scope (session, authenticated users vs anonymous), and pairs with recall/forget for complete usage pattern.

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, which indicate safe, read-only behavior. The description adds value by revealing that each call cascades through several lookup endpoints internally, which explains potential latency but also consolidates effort. 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 front-loaded with example queries to immediately convey the tool's purpose. It is structured into clear sections: example queries, usage instruction, and supported types with details. While it is somewhat lengthy, every sentence adds necessary information. Minor redundancy (e.g., stating 'resolves to canonical ID' twice) could be trimmed, but overall it is 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?

Given the complexity of handling two distinct entity types (company and drug) with different input and output formats, and the absence of an output schema, the description fully explains what each call returns and what inputs are accepted. It also covers edge cases like auto-disambiguation for companies. The tool is presented as a comprehensive resolver that replaces multiple manual lookups, meeting all contextual needs.

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. The description goes significantly beyond the schema by specifying exactly what is returned for each entity type (e.g., for company: ticker, 10-digit CIK, company_name, and citation URI; for drug: RxCUI, ingredient, brand, and citation). It also clarifies acceptable input formats (ticker, CIK, name for company; brand/generic for drug). This provides crucial context for correct parameter usage.

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

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

The description explicitly states the tool's function: resolving a user-spoken name to a canonical/official identifier. It provides clear examples of queries ("What's the ticker for…", "find the CIK for…") and the entity types supported. This makes the purpose highly specific and distinguishable from sibling tools like compare_entities or entity_profile, which serve different functions.

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 includes an explicit directive: "Use FIRST whenever you have a name but need an ID." This clearly indicates when to use this tool. It also notes that it replaces 2-3 manual lookups, providing context on its efficiency. However, it does not explicitly mention when NOT to use it or what alternatives exist if the entity type is not supported.

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, openWorldHint, and destructiveHint as safe. The description adds behavioral details beyond annotations: it uses ai_visibility_check for each probe, ranks results, and returns a ranked list with score, confidence, and signal density. It also specifies entity count (2-8) and treatment of first entry as subject. 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 main description is three sentences, front-loaded with the primary purpose and key actions. Every sentence adds value: first states purpose, second explains mechanism, third provides a concrete example. No extraneous information.

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

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

Given no output schema, the description adequately explains the return format (ranked list with score, confidence, signal density). It also specifies input constraints (2-8 entities) and the probe method (ai_visibility_check). For a tool with annotations already covering safety, this provides sufficient context for an agent to use the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds significant meaning beyond property descriptions: specifies default model (workers-ai), explains _apiKey requirement only when anthropic model is used, clarifies context purpose, and notes first entity is treated as subject. This enriches the schema, justifying a score above baseline.

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

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

The description clearly states the tool compares AI visibility across multiple entities, probing each with ai_visibility_check, ranking by score, and surfacing most/least recognized. It uses specific verbs (compare, probes, ranks) and distinguishes from sibling ai_visibility_check (single-entity) by focusing on side-by-side comparison.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') and an example ('does Claude know about us as well as our competitors?'). It implies when to use this tool (multi-entity comparison) but does not explicitly exclude alternatives like using ai_visibility_check for single entities or compare_entities for non-AI comparisons. However, the context is clear enough for an agent to infer appropriate 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?

Annotations already provide readOnly, openWorld, idempotent, destructive hints. Description adds partial failure handling, potential 5-30s delay on bundlephobia first measurement, and sources_failed listing.

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 slightly long. Every sentence adds value, but could be tightened slightly 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?

For a complex multi-source tool with no output schema, description fully explains return fields, partial failures, timing, and ecosystem scope. Complete for agent decision-making.

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%, so baseline 3. Description adds that scoped packages are accepted and version defaults to latest. Slight extra 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?

Description clearly states it's a composite check for npm packages covering deps.dev and bundlephobia, with specific return fields. Distinguishes from siblings like scan_competitor_ai_presence by focusing on dependency evaluation.

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

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

Explicitly says 'Use whenever an agent asks 'is X safe / popular / small'' and notes ecosystem limitation: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Discloses specific technical details like BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and return of offsets and similarity scores. All annotations are consistent and description adds significant value 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?

Very concise: two sentences plus a technical note. All information is front-loaded, and every sentence adds value without redundancy.

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

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

Covers purpose, usage, behavioral details, parameters, and limitations effectively. Even without an output schema, the description adequately explains what agents receive (passages with offsets and scores).

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

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

Schema has 100% coverage; description adds meaningful usage context for all three parameters, including examples for query and clarification on text source. However, limit default and range are already in schema, so a slight deduction for not providing additional semantics.

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 performs semantic search inside a fetched record, uses specific examples like SEC 10-K body and article, and distinguishes itself from siblings by focusing on internal search rather than broader queries.

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 ('record is too big to cram into the prompt') and how it pairs with ask_pipeworx_grounded, providing clear context for when this tool is appropriate over 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, so the safety profile is clear. The description adds that it returns listings of databases, folders, and tables, providing behavioral context beyond the annotations.

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

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

Two concise sentences with the purpose front-loaded. Every sentence adds value; no wasted words.

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

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

With one parameter, good annotations, and no output schema, the description is nearly complete. It explains the navigation and listings but could benefit from mentioning the output format (e.g., JSON structure) for full 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?

The single parameter 'path' has a description with a default value and an example, adding context beyond the schema coverage of 100%. The example helps the agent understand the format expected.

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 navigates the database/subject tree, listing databases at root and folders/tables at sub-paths. It uses specific terminology and distinguishes itself from sibling tools which are mostly unrelated.

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 exploring the tree structure but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or alternative recommendations are provided.

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

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

Annotations are complemented by the description, which adds details on OAuth requirement, delivery channels, constraints (e.g., SMS 10/day cap, webhook auto-disable). No contradiction with annotations, though idempotentHint true could be clarified in the description.

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

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

The description is dense but well-structured, with the first sentence establishing purpose. Despite length, each sentence provides necessary detail for a complex tool. Minor redundancy could be trimmed but overall efficient.

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

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

Given the tool's complexity (3 params, nested objects, no output schema), the description covers requirements, types, delivery options, and return value. It lacks error handling details but is sufficient for standard usage.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema, including type-specific examples and delivery constraints like phone verification and webhook signing. This aids correct parameter usage.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' with a specific verb and resource. It distinguishes itself from siblings 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 explicit context on when to use the tool: for creating subscriptions. It mentions the required OAuth account and lists supported types with examples. However, it doesn't explicitly state when not to use alternatives, which would improve clarity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint false. The description adds behavioral details about returning category-bucketed example questions with tool and argument shapes, and explains behavior with no arguments vs. topic. 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?

Front-loaded with common queries and then provides detailed explanation. Slightly verbose but every sentence adds value.

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

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

Despite lacking an output schema, the description fully explains what the tool returns and how to use it. No missing information for an onboarding tool.

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

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

Schema coverage is 100% and the description enriches the single optional parameter by explaining when to omit it (for cross-category spread) and listing example 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 identifies the tool as an onboarding entry point that returns categorized example questions with tool shapes. It uses specific verbs and resources, distinguishing it from sibling tools like ask_pipeworx and entity_profile.

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

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

Explicitly states 'Use this FIRST when you do not yet know what Pipeworx can do for you' and provides alternatives. Also explains when to use the optional topic parameter.

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, covering safety and idempotency. The description adds minimal behavioral context beyond stating the returned information type. It does not disclose any additional traits like permissions, rate limits, or response structure.

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

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

The description is extremely concise with one clear sentence and one constraint. Every word serves a purpose, and the core function is front-loaded. No unnecessary content.

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

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

Given that there is no output schema and the tool is simple with a single parameter, the description is functional but incomplete. It does not describe the structure or extent of the returned metadata, such as whether it includes value lists, types, or additional properties. More detail would help the agent 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% with a parameter description and example. The description adds value by specifying the '.px' suffix constraint, which is not in the schema. This clarifies the expected format beyond the example, aiding correct invocation.

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

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

The description clearly states that the tool provides 'Table definition (dimensions, valid values)', which is specific about the resource and action (retrieving metadata). However, it does not explicitly use a verb like 'get' or 'retrieve', but the meaning is unambiguous. It distinguishes itself from siblings like 'query_table' which likely queries 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 includes one guideline: 'Path must include the '.px' table suffix.' This is useful but there is no further guidance on when to use this tool versus alternatives such as 'query_table' or 'discover_tools'. No when-not-to-use or alternative recommendations are provided.

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

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

The description adds behavioral context beyond annotations: ownership check, deactivation (not deletion), and preservation of historical events. No contradiction with annotations.

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

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

Three sentences, front-loaded with the main action, no wasted words. Efficient and clear.

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

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

Given only one required parameter, no output schema, and supportive annotations, the description provides sufficient context: outcome, ownership, and data retention implications.

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 single parameter 'id' is fully described in the input schema (100% coverage), and the description adds no extra detail about its format or usage beyond what the schema provides.

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

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

The description uses a specific verb-resource combination ('Cancel a subscription') and clearly distinguishes from siblings like 'subscribe' and 'list_subscriptions'.

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

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

It states ownership enforcement ('you can only cancel your own subscriptions') and explains the outcome (deactivation vs deletion), but does not explicitly mention when not to use or name alternatives.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds detailed behavioral context: it returns a verdict with five specific categories, an extracted structured form, actual value with a pipeworx:// citation, and percent delta. It also discloses the data sources (SEC EDGAR + XBRL). 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, well-structured paragraph that is front-loaded with the most critical information (trigger phrases, purpose). Every sentence earns its place, covering domain, usage, output, and efficiency benefit without 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 thoroughly explains the return format (verdict, extracted form, actual value, citation, delta). Given the tool's moderate complexity, this provides sufficient completeness for an agent to select and invoke it correctly.

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

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

The single parameter 'claim' has 100% schema description coverage, so the schema already defines it. The description adds value beyond the schema by providing typical phrasing examples and clarifying the natural-language nature. This gives the agent richer understanding, warranting a score above baseline.

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

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

The description immediately signals the tool's purpose with trigger phrases like 'Is it true that…' and 'fact check'. It clearly states it does natural-language claim verification against authoritative sources, and distinguishes itself from siblings by noting it replaces multiple sequential calls. The domain (company-financial claims) is explicitly specified.

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 'Use whenever the agent needs to check whether something a user said is factually correct.' It provides examples and notes efficiency gains. While it doesn't explicitly state when not to use, the domain restriction is clear. Alternatives are not named, but the context of sibling tools and specialization is evident.

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