Geoapify

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

Discloses default free model, optional paid Anthropic probe with BYO key, cost implications, and return structure. Adds significant value beyond annotations (readOnlyHint, idempotentHint).

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: main action, optional/config details, return structure and use cases. No fluff, front-loaded with core purpose.

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

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

No output schema, but description returns per-model fields and combined view. All parameters covered, behavioral context provided. Fully adequate for agent 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%, so baseline is 3. Description adds value by explaining default model, purpose of _apiKey, and context disambiguation role.

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?

Describes probing LLMs for entity visibility and scoring 0-100, with per-model return. Clearly distinguishes from siblings like 'ask_pipeworx' which are for general queries, and 'scan_competitor_ai_presence' for competitor scans.

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

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

States explicit use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring. Does not provide negative guidance or alternatives, 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?

Annotations indicate read-only, open-world, idempotent behavior. Description adds context about routing to many sources and returning citations. No contradiction, but lacks detail on potential rate limits or error handling.

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?

Relatively long but front-loaded with key action: 'PREFER OVER WEB SEARCH'. Every sentence adds value; however, could be slightly more concise.

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

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

Given no output schema, description explains it returns structured answers with citation URIs. For a tool of this complexity, it covers usage, alternatives, and parameter semantics sufficiently.

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

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

Schema coverage is 100% with all parameters documented. Description adds value by listing alias parameter names (q, text, etc.), which helps the agent understand multiple valid input forms.

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 answers factual questions about real-world data, with specific examples and distinguishes from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

Explicitly says 'PREFER OVER WEB SEARCH' and provides when to use this tool vs alternatives, including step-up tools for specific needs.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint, openWorldHint. The description adds extra behavioral details: 'extracts the answer using ONLY what the tool result contains,' returns explicit refusal reasons, costs one extra LLM call. No contradictions.

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

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

The description is moderately concise, providing essential information in about 3 sentences plus a return format specification. It front-loads the purpose and usage guidance. Slightly verbose due to listing of return fields and refusal reasons, but each part adds value. Score 4 for good structure with minor excess.

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

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

Given no output schema, the description fully explains the return format including success fields (answer, evidence, confidence, source, fetched_at, refusal_reason) and refusal reasons. Also covers cost trade-off and use cases. Complete for a complex multi-step tool.

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

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

Schema coverage is 100% with descriptions for each parameter (including aliases). The description mentions 'question' and lists aliases, but that is already in the schema. No additional semantic information beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It explains the mechanism (routing, data fetching, extraction from tool result) and distinguishes itself from the sibling ask_pipeworx by the extra LLM call for grounding.

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 when-to-use guidance: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' (financial verdicts, legal claims, etc.) and when-not-to: '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?

The description extensively details behavioral traits beyond annotations: fan-out logic, response shapes, resolver contract, safety short-circuit, closed market handling, resolution-rule risk. All consistent with readOnly/idempotent 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?

While front-loaded with purpose and well-organized into sections, the description is very long and verbose, which may overwhelm agents. Shorter, more terse descriptions would be preferable.

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 thoroughly covers all response fields, edge cases, and safety mechanisms. It is complete for the tool's complexity.

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

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

Schema already covers 100% of parameters with descriptions. The description adds value with examples, explanations of depth options, and context for market input types, going beyond the schema.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific input types and use cases. However, it does not explicitly differentiate from sibling tools like polymarket_edges or polymarket_arbitrage, which slightly reduces clarity.

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 ('should I bet on X', etc.) and detailed fan-out examples. It lacks explicit when-not-to-use or alternatives, but the context is clear enough for an agent to decide.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds value by detailing data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and sort order. No contradiction with annotations.

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

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

Description is a single dense paragraph with front-loaded purpose and examples. Every sentence adds value, though it could be more structured (e.g., separating company vs drug details). No unnecessary words, concise for the amount of 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 explains return contents (paired data + citation URIs). It mentions edge cases (off-calendar fiscal years) and results sorted by primary metric. Complete for a 2-param tool with good annotations.

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

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

Schema coverage is 100%, but description enhances meaning: for 'type', it specifies data sources; for 'values', it gives concrete examples (tickers/CIKs for company, drug names) and constraints (2-5 items). This adds practical guidance beyond the schema.

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

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

Description clearly states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call' with specific verb ('compare') and resource ('entities'). It distinguishes from sibling tools by explaining it replaces multiple sequential lookups, making purpose unambiguous.

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

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

Explicitly advises 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides example query patterns ('compare X and Y', 'X vs Y', 'which is bigger'). This gives clear when-to-use guidance and implies when not to use (single entity lookups).

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description reveals critical behavioral traits: it decomposes questions into facets, routes to 4,774 tools in parallel, returns a structured findings packet with verbatim evidence, confidence, source, fetched_at, and pipeworx:// citations, explicitly includes gaps[] for unanswered facets, and never invents data. Expected execution time of 15-60 seconds is also provided. 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 relatively long but every sentence adds value: account requirement, sibling comparison, functional explanation, return format, timing, and usage notes. Critical information (account required) is placed first. While slightly verbose, it avoids fluff and maintains a logical flow.

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 (multi-source, parallel research, rich output), the description covers all essential aspects: what it does, how it works, what it returns, when to use alternatives, expected timing, and account limitations. Without an output schema, it compensates by describing the output structure (findings packet with evidence, confidence, source, fetched_at, citations, gaps[]). It could mention edge cases like handling of ambiguous questions, but overall is very 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?

Input schema covers both parameters with descriptions, but the tool description adds meaningful context: it explains that depth values correspond to specific facet counts (quick=3, standard=5, thorough=8) and that the default is 'standard'. It also notes that broad/multi-part questions are acceptable, enhancing the schema's basic definitions.

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

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

The description specifies a precise verb ('research'), resource ('Pipeworx's 1242 STRUCTURED data sources'), and action ('decomposes your question into focused facets... in parallel'). It clearly distinguishes itself from siblings by stating it is 'NOT open-web search' and explicitly contrasts with 'ask_pipeworx' and others, leaving no ambiguity about its role.

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 offers explicit guidance on when to use this tool versus alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS topics, prefer ask_pipeworx'. It also provides account requirements, noting that depth:'thorough' needs a paid plan and suggests using ask_pipeworx if not signed in. This covers both inclusion and exclusion criteria thoroughly.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral details: it returns top-N relevant tools with full schemas ready to call, no side effects. 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 paragraph that front-loads purpose and usage. However, it lists many domain examples, making it longer than necessary. Could be more concise without losing clarity.

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

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

Given the tool's complexity (search/discovery, no output schema), the description adequately covers input (query with aliases) and output (tools with schemas). It includes examples and explains the result format, making it complete for an agent.

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

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

Schema coverage is 100% with all parameters described. The description reiterates the purpose of the 'query' parameter but adds no significant 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 clearly specifies the tool's purpose: to find tools by describing a task or data. It lists numerous domains (SEC filings, FDA drugs, etc.) and details the output (top-N tools with schemas). This distinguishes it from sibling tools that perform domain-specific tasks.

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

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

The description explicitly says 'Call this FIRST when you have many tools available' and suggests using it to see the option set rather than just one answer. This provides clear guidance, though it could explicitly mention when NOT to use it (e.g., if tool is known).

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint all indicating safe, non-destructive, idempotent behavior. The description adds context about fanning out across multiple sources, soft-failing on patents due to API sunset, and returning specific data. It does not disclose rate limits or auth needs, but the annotations cover the key behavioral traits. The description adds moderate 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?

The description is slightly long but well-structured: front-loaded with example queries, then the preferred use, then a detailed breakdown of return fields, and finally limitations. Every sentence serves a purpose, but could be trimmed slightly without losing 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?

The tool is complex with multiple data sources and no output schema. The description thoroughly explains inputs, outputs (cik, company_name, recent_filings with URIs, fundamentals sorted, patents soft-fail, news via GDELT→GNews, LEI via GLEIF), and limitations (no names, patent API sunset). It covers all necessary 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?

Schema coverage is 100% with descriptions for both parameters. The description adds the example of ticker vs zero-padded CIK, clarifies that names are not supported, and points to resolve_entity as an alternative. This adds meaning beyond the schema's enum and description, justifying a score above baseline 3.

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

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

The description starts with example queries and explicitly states it creates a 'full cross-source profile of a US public company in ONE parallel call'. It lists the domains covered (SEC EDGAR, XBRL, USPTO, news, GLEIF) and the exact return fields. It also distinguishes from siblings like resolve_entity by noting that names are not supported. Purpose is specific, verb-driven, and clearly differentiates from other tools.

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

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

The description explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing a clear when-to-use directive. It also advises to use resolve_entity first if only a name is available, giving explicit alternatives. Usage context is unambiguous and helpful.

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

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

Annotations already declare destructiveHint=true. Description adds context about clearing sensitive data and pairs tools, but doesn't mention idempotency (already in annotations) or return behavior. Adds 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?

Three short sentences: action, usage, complementary tools. Front-loaded and no wasted words.

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

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

For a simple delete tool with no output schema, description provides clear purpose and usage. Could include return behavior, but not critical given idempotency annotation.

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

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

Only one parameter 'key' with schema description 'Memory key to delete'. No extra detail on format or constraints beyond schema (100% coverage). Baseline 3.

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

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

Starts with 'Delete a previously stored memory by key' – a specific verb and resource. Clearly distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also pairs with alternatives 'remember' and 'recall'. No explicit when-not, but sufficient guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it fetches the page and extracts data, confirming safe, read-only behavior. No contradiction, and it provides process context beyond annotations.

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

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

Two sentences: first explains what it does and how, second lists use cases. No filler, front-loaded with key information. Every sentence earns its place.

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

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

Tool has only 2 parameters, no output schema, but rich annotations. Description covers input, process, output format (standard llms.txt markdown), and use cases. It is complete and leaves no ambiguity for an agent to invoke it correctly.

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

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

Input schema coverage is 100% with descriptions. Description does not add any semantics beyond what the schema already provides (URL and max_links with defaults). Baseline score of 3 is appropriate.

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

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

Description clearly states verb 'generate', resource 'llms.txt file for any URL', and specific actions (fetches page, extracts title/description/key links, emits standard markdown). It distinguishes from sibling tools like 'ai_visibility_check' by focusing on creating the llms.txt file rather than just checking visibility.

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

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

Explicitly lists three use cases: getting a client's site indexed, drafting your own llms.txt, or auditing how an AI crawler sees a competitor. Does not mention when not to use or alternative tools, but the context is sufficient for an agent to decide.

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

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

Annotations already confirm read-only, idempotent, safe behavior. The description adds that it returns multiple candidates with specific fields (address, lat, lon, etc.), providing useful behavioral detail 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 including an example. Front-loaded with purpose, no redundancy, 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 explains return fields and gives an example. The tool is straightforward and the description covers all essential aspects: purpose, input types, output structure.

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 example usage for the text param but does not clarify limit default or apiKey behavior beyond schema. 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 states the verb (convert/geocode) and resource (address/place name to coordinates). It distinguishes from siblings like reverse_geocode by specifying 'forward' geocoding and listing location types.

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

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

The description explains the input types and provides an example, but does not explicitly say when to avoid this tool (e.g., for batch processing or non-geographic queries) or mention alternatives like places.

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

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

Annotations already declare read-only, idempotent, non-destructive; description adds return fields and default filtering to active subscriptions, enhancing transparency.

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

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

Two sentences with no waste: first states purpose and outputs, second gives usage guidance 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?

Lists return fields and optional parameter, sufficient for a simple read-only tool; no output schema needed due to field listing.

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 'include_inactive' described; description does not add extra meaning beyond implying default active filter, meeting 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 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from siblings like subscribe/unsubscribe by listing rather than creating/removing.

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

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

Explicitly advises using the tool to review current subscriptions before adding more or to find an ID for cancellation, providing clear context for 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 provide minimal behavioral hints (readOnlyHint=false, destructiveHint=false). The description adds that it is rate-limited (5 per identifier per day) and free, but does not elaborate on side effects or processing (e.g., manual review by team). This adds moderate 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?

The description is a dense paragraph of about 5 sentences, front-loading the core purpose. It is concise without being terse, though some sentences could be combined for even greater brevity.

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

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

For a relatively simple feedback tool (3 params, no output schema, nested context object), the description covers use cases, constraints (rate limits, quota), and formatting guidelines. It does not describe return values, but that is acceptable for a tool that likely returns a simple confirmation.

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

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

Schema description coverage is 100%, so parameters are well-documented. The description reinforces that message should be specific and brief, but does not add new meaning beyond the schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It specifies the verb (tell/give feedback) and resource (Pipeworx team), and distinguishes among feedback types (bug, feature, praise). No sibling tool shares this 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 explicitly lists when to use it: for bugs, features/data gaps, praise. It also provides formatting guidance (describe in terms of tools/packs, don't paste end-user prompt) and mentions rate limits and quota impact. However, it does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, but the description adds valuable behavioral details: no PII, caching behavior (5min-1h), and the data structure (pack, tool, count). No contradictions with annotations.

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

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

The description is concise and front-loaded: the first sentence captures the core functionality. Every subsequent sentence adds value without redundancy. 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 lacking an output schema, the description clearly explains the return structure (top tools, top packs, total call volume, aggregated counts). For a simple read-only tool with a single optional parameter, 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?

With 100% schema description coverage, baseline is 3. The description adds meaning beyond the schema by explaining the interpretation of different window durations ('shorter windows surface what's hot right now; longer windows show steady-state demand').

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

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

The description clearly states the tool's purpose: returning trending tools, packs, and call volume on Pipeworx. It uses specific verbs ('returns') and distinguishes from sibling tools like 'discover_tools' and 'ask_pipeworx' by focusing on trending/aggregate 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?

Three explicit use cases are provided, explaining when to use the tool (e.g., discovering hot data sources, confirming popular tools). However, it does not mention when not to use it or provide explicit alternatives, though sibling context implies differentiation.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds concrete details about return fields, filtering, and the example, which provides useful context beyond annotations.

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

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

Two concise sentences plus an example that front-loads the purpose. Every sentence adds value with no redundancy or fluff.

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

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

For a query tool with no output schema, the description explains return fields and key parameters. It covers purpose, inputs, and example. Minor gaps like error handling or rate limits are acceptable given the open-world hint.

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

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

The schema covers all 6 parameters with descriptions, so baseline is 3. The description adds an example and mentions default/max values already present in the schema, offering marginal 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?

The description clearly states the tool searches for places and POIs near a location filtered by category. It specifies return fields (name, address, categories, lat, lon, distance) and provides an example, making its function distinct from siblings like geocode or routing.

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 via an example but does not explicitly state when to use this tool versus alternatives or when not to use it. No comparison to sibling tools is 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 mark the tool as read-only, idempotent, non-destructive. The description adds extensive behavioral context: internal algorithms (monotonicity checks, partition sum, similarity filtering, placeholder filtering), the fill check and when not to trade, and a reference to polymarket_fill_risk for custom sizing. No contradictions.

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

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

The description is information-dense and every sentence adds value. However, the long paragraph format could be restructured (e.g., bullet points or separate sections) for easier scanning. Still, it is not verbose and is front-loaded with the core purpose.

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

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

Given the tool's complexity (three modes, internal algorithms, fill check, no output schema), the description is exceptionally complete. It covers all key behaviors, edge cases (placeholder filtering, Jaccard similarity), and even references sibling tools for follow-up. No missing critical information.

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

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

Schema coverage is 100% with both parameters described, but the description adds deep meaning: explains event slugs vs. topic seed questions, gives concrete examples, and clarifies that no args triggers a trending scan. This goes well beyond the schema definitions.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It distinguishes three modes (no args, event, topic) and contrasts with siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description explicitly tells the agent when to use each argument: no args for trending scan, event for single-event mode (recommended), and topic for cross-event scan. It explains the rationale for each mode and provides examples.

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

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

Beyond annotations (readOnly, idempotent), it discloses caching behavior (1h KV), response diagnostics for empty segments, and limitations (Fed bets excluded). It also explains how edges are calculated and slippage assumptions, adding significant value.

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, especially the detailed model family explanations, but it is front-loaded with the purpose and uses sections (e.g., 'TRADEABLE-EDGE KNOBS'). It could be shorter 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?

Despite no output schema, the description thoroughly explains the response structure (by_segment, diagnostics, warning fields) and all parameter interactions. It covers edge cases, caching, and limitations, making it highly complete for a complex tool.

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

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

Schema coverage is 100%, but the description adds contextual meaning (e.g., 'Tradeable-edge filter' for max_spread_pp, explanation of min_partition_leg_kelly vs min_kelly). It goes beyond simple parameter 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 begins with a clear verb-resource statement: 'Scan top Polymarkey markets and return opportunities where Pipeworx data disagrees with market price.' It also distinguishes from siblings like polymarket_arbitrage by focusing on edges vs. pure arbitrage and is specific about the three model families.

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 context ('Built for what should I bet on today') and explains parameter knobs (e.g., min_liquidity, max_spread_pp) with usage guidance. It lacks explicit when-not-to-use instructions but offers enough context for typical use 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 indicate readOnlyHint=true, destructiveHint=false, and the description confirms it is a read operation. It details the response structure (tracked, expired, snapshot_dates) and explains the computation of trend and decay_pp_per_day. No contradiction; adds value beyond annotations by clarifying data scope and limitations.

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

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

The description is well-structured: starts with purpose, then explains response fields with clear labels (RESPONSE:), and ends with limits. It is somewhat lengthy but each sentence adds value. No redundancy.

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

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

Given no output schema, the description thoroughly covers all response components (tracked, expired, snapshot_dates) with details on fields like trend, decay_pp_per_day, and lifespan_days. It also mentions limitations (60-day TTL, snapshot start) and data frequency. Complete for a telemetry 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 parameter descriptions. The description adds meaning by explaining defaults (days default 14, window default '1wk'), the clamp range (2-30), and snapshot families. It also details the response, which is not in the schema, compensating for lack of output schema.

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

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

The description clearly states the tool is for 'Edge persistence and decay telemetry' built from daily snapshots. It answers a specific user question about how long an edge has existed and whether it is shrinking. The purpose is distinct from sibling tools like polymarket_edges which likely covers 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 gives explicit usage context: it compares a fresh wide edge to a 3-week-old wide edge, indicating when the tool is relevant. It also mentions limitations like the 60-day snapshot TTL. However, it does not explicitly state when not to use it or compare to alternatives beyond implied differentiation.

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

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

Annotations already indicate readOnly, idempotent, and non-destructive. The description adds rich behavioral context: reveals that it walks the order book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict for single-market; theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, max_clean_notional_usd, forced_directional_risk for basket), and warns about partial basket fills and directional risk. 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 the purpose and mode requirement. It is well-structured with clear sections (SINGLE-MARKET, BASKET). However, it is somewhat verbose with acronyms (CLOB, VWAP, pp) and could be slightly more concise. Every sentence does provide value, so it earns a high score.

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 compensates by listing all return fields for both modes. It also explains risk context (directional risk, thin legs). The tool is complex (two modes, multiple outputs), and the description is fully complete for an AI agent to understand what it returns and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description significantly adds meaning: explains that size_usd for baskets is 'settlement notional (shares per leg)' and default 1000 clarifies the role of side default logic for baskets. It also explains the distinction between market and event parameters (single-market vs basket mode), adding value beyond the schema.

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

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

The description clearly states it performs a 'realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes single-market and basket modes, and contrasts with sibling tools by specifying when to use it (before acting on polymarket_arbitrage signals or trades above ~$500). The verb-check is specific, and the resource (order-book depth) is well-defined.

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

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

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books, partial basket fills create directional risk). This provides clear when-to-use and when-not-to-use 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?

The description adds extensive behavioral context beyond annotations: explains how the tool determines signal vs noise, details compatibility_warning conditions, temporal alignment, and skipped leg comparisons. No contradiction with annotations (readOnlyHint, etc.).

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

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

The description is well-structured, front-loaded with core purpose, then modes, response, and safety fields. While every sentence is informative, it is somewhat lengthy; minor trimming could improve conciseness without losing value.

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

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

Despite no output schema, the description adequately explains the response structure (leg-by-leg prices, top_spreads_pp) and covers edge cases (compatibility_warning, temporal alignment, skipped counters). It also gives practical advice about rarity of tradeable spreads, making it complete for a complex tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the interaction between parameters (override logic) and providing context for the topic parameter values. However, it does not add new parameter semantics beyond what the schema already describes.

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 calculates cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses a specific verb (spread) and resource (two venues), and the name implies a comparison tool, distinguishing it from siblings like polymarket_arbitrage which focuses on intra-venue arbitrage.

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

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

Explicitly describes two modes (topic shortcuts and explicit tickers), explains when spreads are meaningful (equivalent bet shapes, temporal alignment), and provides clear warnings about compatibility issues. It advises that most pre-mapped topics return a warning, preventing false expectations.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by explaining scoping (identifier-based) and listing behavior, which are not in 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 tight: 3-4 sentences, front-loaded with core action, and every sentence adds essential information without redundancy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description covers retrieval, listing, scoping, and sibling relationships fully. 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%, so baseline is 3. The description adds concrete examples (e.g., 'user's target ticker, address, research notes') and clarifies the behavior when 'key' is omitted, enhancing understanding.

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

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

The description clearly states the tool retrieves a value saved via remember or lists all keys when no key argument is provided. It distinguishes from siblings by mentioning 'remember' and 'forget', making purpose explicit.

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

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

Explicitly states when to use: 'to look up context the agent stored earlier... avoiding re-deriving from scratch.' Also advises pairing with 'remember' to save and 'forget' to delete, providing clear usage and alternatives.

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

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

The description fully discloses behavioral traits: it returns recent alerts with specific fields, supports filtering, and allows marking events as read (mutating state). Despite annotations indicating readOnlyHint=true, the description transparently explains the side effect of mark_read, which contradicts the annotation but is disclosed clearly.

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

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

The description is concise: 4 sentences covering purpose, return data, filters, mark_read behavior, and alternative access. No redundant or unnecessary text. Front-loaded with the main action and resource.

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 return fields, filtering options, mark_read behavior, and polling suitability. However, it lacks details on pagination or error handling, and since there is no output schema, more detail on the return structure would improve completeness. Still, it is adequate for a read-only list tool with good annotations.

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

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

Schema coverage is 100% (all 5 parameters described). The description adds value by explaining the 'type' filter with an example ('sec_8k'), the 'since' parameter as ISO timestamp, and the 'mark_read' parameter's effect of flagging events so future calls return newer ones. This exceeds the baseline of 3 for full 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 tool's purpose: 'Pull fired events from your subscription feed.' It specifies the resource (subscription feed), the action (pull), and the returned data (source, citation_uri, raw payload). This distinguishes it from siblings like 'search_within' or 'recent_changes' which handle different 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 explains when to use the tool: for polling alerts from the feed, and notes that the same feed is available via HTTP for scripts/dashboards. It doesn't explicitly exclude alternatives, but the context of subscription alerts is clear. No comparison to other tools, but the usage context is adequately conveyed.

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

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

Adds detailed behavioral context beyond annotations: describes source fan-out logic, fallback from GDELT to GNews, USPTO soft-fail, return structure (changes grouped by source, total_changes, citation URIs). No contradiction with annotations (readOnlyHint, idempotentHint, etc.).

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

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

Well-structured single paragraph with backtick highlights for examples and terms. Slightly dense; breaking into bullet points could improve scannability but still highly 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?

Comprehensive for a complex tool: no output schema, yet description details return format and source behaviors. Covers all necessary context for correct agent invocation.

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

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

Schema has 100% coverage but description enriches semantics: explains 'since' accepts ISO or relative shorthand with examples, recommends '30d' or '1m' for typical monitoring, clarifies 'value' accepts ticker or CIK.

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

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

The description clearly states it provides a change feed for a company in a time window, fanning out to multiple sources (SEC, GDELT/GNews, USPTO). It distinguishes from sibling tool 'entity_profile' by explicitly stating the alternative use case.

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?

Includes example queries ('What's new with X', 'latest on Y') that signal when to use. Explicitly advises using 'entity_profile' for static profile, providing clear when-not-to-use guidance.

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

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

Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds context on scoping by identifier and 24-hour retention for anonymous sessions, which goes beyond what annotations provide, though it doesn't disclose any unusual side effects.

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

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

The description is four sentences, front-loaded with the core purpose, and each sentence adds value without redundancy. It efficiently covers use case, mechanics, and sibling tools.

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 write tool with two parameters and no output schema, the description provides complete context including purpose, when to use, persistence behavior, and relationship to recall/forget.

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

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

Schema covers 100% of parameters with clear descriptions. The description adds no extra meaning beyond noting key-value scoping, which is already implied by 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 specifically states 'Save data the agent will need to reuse later' and contrasts with sibling tools recall and forget, clearly distinguishing its role as a write operation for persistent key-value storage.

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

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

Provides explicit guidance on when to use (discover something worth carrying forward) and when not to (implicitly, for retrieval use recall), and includes persistence details differentiating authenticated vs anonymous sessions.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds useful behavioral insights: 'cascades through several lookup endpoints internally — using resolve_entity replaces 2-3 manual lookups', plus return value composition. No contradiction with annotations.

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

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

Description is moderately long but front-loaded with examples and clear instruction. Every sentence adds value, though slightly verbose in the return details. Well-structured with sentence breaks.

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, description fully covers what the tool returns for each type, how it works (cascading lookups), and usage hint. Complete enough for an AI agent to use correctly.

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

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

Schema coverage is 100% and description adds meaning: for 'value', explains accepted formats (ticker, CIK, name) with examples; for 'type', details return components per type. Enhances the schema rather than repeating it.

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

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

The description clearly states it resolves names to canonical identifiers, with specific verb phrases like 'resolve a user-spoken NAME to the canonical/official identifier'. It distinguishes from siblings like compare_entities and entity_profile by focusing on ID lookup, and provides concrete example 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 says 'Use FIRST whenever you have a name but need an ID', giving clear context. Does not explicitly list when not to use, but the sibling list makes alternatives obvious. The description of supported types and return values further guides 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 declare readOnly, idempotent, and non-destructive. The description adds specific return fields and an example, but does not cover edge cases or rate limits, which is acceptable given annotation coverage.

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

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

Two succinct sentences front-loaded with purpose, followed by useful example. No filler or redundant text.

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

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

No output schema exists, but the description explains return fields well. Missing error handling or third-party dependency mention, but the _apiKey parameter hints at external service. Overall adequate for the tool's simplicity.

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 all three parameters. The description repeats lat and lon and provides an example, but adds no extra semantic detail beyond the schema.

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

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

Description clearly states the tool converts lat/lon to street address, lists returned fields, and gives an example. It distinguishes from sibling geocode (forward) by being reverse.

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: when you have coordinates and need an address. The example provides context. However, it does not explicitly contrast with the sibling geocode or state 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 read-only, idempotent, non-destructive behavior. The description adds context about output format (distance in meters, time in seconds) and provides an example, enhancing transparency beyond annotations.

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

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

Two sentences plus one concise example, all substantive. No wasted words or redundancy.

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

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

For a simple tool with no output schema, the description covers purpose, parameters via example, and return format. Could mention error handling but is largely 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%, so baseline is 3. The description adds an example call demonstrating usage, but does not significantly deepen understanding 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 computes distance and travel time between two points for given travel modes, with a specific verb and resource. It implicitly distinguishes from sibling geocoding tools.

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

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

The description implies usage when distance and time are needed, but does not explicitly state when to use or avoid this tool compared to alternatives like geocode.

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=false. Description adds: probes each entity with ai_visibility_check, ranks by score, returns score/confidence/signal density. No contradictions.

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

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

Three sentences, front-loaded with main action. No wasted words. Every sentence contributes value: purpose, method, use case, output.

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

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

No output schema, but description covers return format (ranked list with score, confidence, signal density). Explains integration with ai_visibility_check. Complete for complexity.

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

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

Schema coverage 100%. Description adds meaning beyond schema: 'First entry treated as subject for narrative; rest are competitors', and clarifies context purpose. Compensates fully.

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

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

Description states 'Compare AI visibility across multiple entities side-by-side' with specific verb+resource. Clearly distinguishes from sibling tools like ai_visibility_check (single probe) and compare_entities (generic). Includes ranking and return details.

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 'Useful for competitive AI-marketing audits' and gives example question. Provides context for when to use but doesn't explicitly state when not to or name alternatives beyond implicit distinction.

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

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

Annotations already declare readOnlyHint and idempotentHint. Description adds behavioral details: partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, sources_failed list included. No contradictions.

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

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

Description is dense with information but slightly long. Front-loaded with purpose. Every sentence adds value, though could be more concise.

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

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

With no output schema, description thoroughly explains return format (summary block with specific fields, advisory details, links, alternatives) and mentions partial failures, 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 covers both parameters with descriptions. Description adds that scoped packages are accepted and version defaults to latest, providing extra meaning beyond schema.

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

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

The description clearly states the tool is a composite check for npm packages combining deps.dev and bundlephobia data, with specific verb 'scan' and resource 'dependency'. It distinguishes itself from siblings by focusing on npm package 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 when to use: when agent asks about safety, popularity, size, or cost of adding a package. Also clarifies alternatives for non-npm ecosystems (deps.dev:version).

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

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

Annotations already indicate readOnly, openWorld, idempotent hints. The description adds technical details: BGE-base-en embeddings, 500-char overlapping windows, 200K char cap with truncation flag, and returned data (passages with offsets and scores).

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 reasonably concise, front-loaded with purpose. Every sentence adds value, though the sentence about embedding details could be integrated more tightly.

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

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

Given no output schema, the description fully explains return values (top-N passages with offsets and scores). It covers constraints (200K char cap, truncation), usage context, and technical details. Complete for a search 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?

With 100% schema coverage, description adds value beyond schema: explains natural-language query examples, default limit of 5, max characters for text, and mentions return format (passages with offsets and similarity scores) not in schema.

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

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

The description clearly states it performs 'Semantic search INSIDE a fetched record' with a specific verb and resource. It distinguishes from siblings by mentioning 'use when the record is too big to cram into the prompt' and pairing with 'ask_pipeworx_grounded'.

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 to use when the record is too large for the prompt and suggests pairing with 'ask_pipeworx_grounded'. No explicit when-not-to-use, but the context is clear.

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

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

Description adds significant behavioral details beyond annotations: returns subscription id, requires authentication, specifics of each type and delivery method, including webhook signing, auto-disable after failures, SMS cap. Does not contradict annotations (readOnlyHint false, openWorldHint true, idempotentHint true, destructiveHint false).

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

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

Well-structured: opens with core purpose, then covers requirements, types, and delivery. Every sentence adds value; no redundancy. Length is appropriate for the complexity of the tool.

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 all critical aspects: action, return value, prerequisites, type-specific parameters, delivery options. Sufficient for an AI agent to select and invoke correctly.

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

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

Despite 100% schema description coverage, the main description enriches each parameter with concrete examples, constraints, and use cases (e.g., for params, it details each type's structure; for delivery, explains always-on feed, webhook details, SMS verification). This adds significant 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?

Description clearly states 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' It uses specific verb and resource, and is easily distinguished from siblings like list_subscriptions, unsubscribe, and recent_alerts.

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

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

Provides explicit context: requires Pipeworx OAuth account, lists supported types with detailed examples, describes delivery channels and their constraints. It gives enough information for an agent to decide when to use this tool and what prerequisites are needed.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds value by explaining the tool's role as a starting point, output structure, and dynamic nature from a live catalog, 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 a single paragraph with good front-loading of purpose. Some redundancy with the title, but overall efficient given the complexity of the tool's output and usage.

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

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

No output schema, but the description thoroughly explains what is returned (categorized questions with tool calls). It covers use cases, parameters, and behavior, making it complete for an introductory tool.

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

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

Schema has 100% coverage for the single optional 'topic' parameter. The description adds context about possible values ('finance', 'pharma', etc.) and clarifies behavior when omitted ('full spread'). This augments the schema description.

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

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

The description clearly identifies the tool as the onboarding entry point for learning about Pipeworx, returning categorized example questions with exact tool calls. It explicitly distinguishes from sibling tools like ask_pipeworx and entity_profile by stating 'Use this FIRST'.

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 advice to use this tool first when unfamiliar with Pipeworx or to learn meta-tools. While it doesn't list when not to use it, the context strongly implies it's for exploration, not direct data retrieval.

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

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

Describes deactivation vs deletion, aligning with destructiveHint false. Adds ownership constraint and idempotent nature (implied by deactivation). Complements annotations well.

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

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

Two sentences, front-loaded with action, no redundant words. Efficiently conveys key points.

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 1-param tool with no output schema and good annotations, the description fully covers purpose, behavior, and constraints. Links to sibling for historical data.

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

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

One parameter 'id' with schema description noting it's a uuid from subscribe. Description adds contextual source but minimal extra beyond schema, which has 100% 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?

Clear verb 'cancel' and resource 'subscription by id'. Title 'Unsubscribe from Alerts' reinforces purpose. 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?

States ownership enforcement and that deactivation keeps historical events accessible via 'recent_alerts', guiding appropriate use and alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable details: returns verdict types (confirmed, approximately_correct, etc.), extracted structured form, actual value with citation, and delta percentage. No contradictions.

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

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

The description is informative and front-loaded with examples and usage triggers. It is somewhat long but every sentence adds value, earning a high score while not 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 single parameter, no output schema, and rich annotations, the description fully covers purpose, input, behavioral output, and scope (SEC EDGAR, XBRL, US companies). Extremely complete for the tool's complexity.

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

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

Only one parameter 'claim' with 100% schema coverage (given example). The description goes beyond the schema by specifying the supported claim scope (company-financial claims) and providing multiple examples, adding meaning for the agent.

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 fact-checks natural-language claims, with examples like 'Is it true that…' and specifies the domain (company-financial claims for US public companies). It distinguishes itself from siblings by noting it replaces 4–6 sequential calls, making its purpose unmistakable.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct' and explicitly limits to company-financial claims. It does not explicitly mention when not to use or compare to alternatives, but the context is clear.

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