Data Austin

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it probes actual LLMs, scores visibility, returns per-model details (including raw_response), notes that passing _apiKey routes calls to Anthropic with user-paid costs, and explains the default model. No contradiction.

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

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

Three sentences with no wasted words. Purpose, usage, and return format are front-loaded. Every sentence adds essential information.

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

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

Given 4 parameters (all documented), no output schema, the description reasonably covers return structure (per-model + combined). It could mention error cases or rate limits, but for a non-destructive, read-only tool, this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the default model, when _apiKey is required, and that 'context' helps disambiguate. This goes beyond the schema's own 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 opens with a specific verb ('Probe') and resource ('LLMs for what they know') and clearly states the output ('score visibility (0-100) per model'). It distinguishes from siblings like 'scan_competitor_ai_presence' by focusing on scoring per model and listing concrete use cases.

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

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

The description explains when to use this tool ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and provides context on default vs. paid models. However, it does not explicitly advise when not to use it or compare to sibling tools.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint as true, so the safety profile is clear. The description adds value by revealing internal routing to 4,482 tools, argument filling, and citation URIs. However, it omits details like rate limits, error behavior, or whether partial results are possible, preventing a perfect score.

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 most critical guidance ('PREFER OVER WEB SEARCH'), then lists use cases, examples, and alternatives. Every sentence adds value; there is no repetition or filler. Despite length, it remains well-structured and scannable.

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 (massive source pool, many siblings), the description is comprehensive. It explains the routing mechanism, return format (structured with citations), and provides a rich set of examples. It covers when to step up to alternatives and clarifies that this tool works on all tiers with one fast call.

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 detailed parameter descriptions for all 6 parameters (5 aliases for question). The description only restates that aliases are accepted, adding no new semantics beyond what the schema provides. Baseline 3 is appropriate given 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: route questions to thousands of verified sources and return structured answers with citations. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, and lists specific domains (SEC filings, FDA data, etc.), making the 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?

Explicit guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and step-up instructions for ask_pipeworx_grounded (hallucination-resistant) and deep_research (broad questions). Also provides examples and types of queries, leaving no ambiguity about when to use this tool.

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

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

Description adds significant behavior beyond annotations: explains extraction mechanism, refusal reasons, return format, and cost (one extra LLM call). No contradictions with annotations.

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

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

Well-structured: purpose, mechanism, return format, usage guidance, trade-off. Every sentence adds value. Front-loaded with key info.

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

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

Complete for a complex tool: explains success/refusal return, refusal reasons, routing to 4482 tools, and cost trade-off. No output schema but description provides the return shape.

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 high-level context about question routing and tool selection. The description mentions aliases but schema already covers that. Slightly above baseline because it explains how parameters are used in the overall workflow.

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

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

Description clearly states the tool's purpose: 'Hallucination-resistant answer mode for high-stakes reads.' It distinguishes from sibling ask_pipeworx by specifying it extracts answers only from tool results and refuses when insufficient.

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: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts.' Provides examples (financial, legal, medical) and advises preferring ask_pipeworx for casual lookups.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds no contradictory or new behavioral details beyond stating what is returned (names, descriptions, ids). It does not discuss behavior like pagination, rate limits, or result ordering, which would add value. Without adding significant context, a score of 3 is appropriate.

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

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

The description is two sentences, extremely concise, and front-loaded with the primary action. Every word is informative, with no redundancy. It efficiently communicates the tool's purpose and 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?

The description explains the return values (dataset names, descriptions, resource ids) and the source website. It connects to the sibling tool 'austin_query', providing workflow context. It lacks explicit mention that results come as a list or that default limit applies, but for a search tool with schema-covered parameters, this is mostly complete. A score of 4 reflects the minor omission.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not mention any parameters or their meanings. The schema itself provides adequate descriptions for all four parameters. The description does not add extra semantic value beyond the schema, so the score remains at 3.

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

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

The description clearly states that the tool searches the Austin open-data catalogue for datasets by keyword. It specifies the action (Search), the resource (Austin open-data catalogue), and the returned data (names, descriptions, resource ids). It also explicitly connects to the sibling tool 'austin_query' for further use, aiding differentiation.

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: to find datasets by keyword and obtain resource ids for use with 'austin_query'. It directly couples this tool with its sibling, but does not explicitly state when not to use it or provide alternative scenarios. However, the context is clear enough for most 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 already declare readOnly, openWorld, idempotent, non-destructive. Description adds context on SoQL capabilities, default and max limits, and optional API key for rate limits.

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

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

Two concise sentences: first defines purpose and SoQL clauses, second guides on finding resource IDs. Front-loaded and 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?

Covers all key aspects: resource ID, SoQL parameters, limits, optional API key, and references discovery tools. No output schema, but description is self-sufficient.

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

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

Schema coverage is 100% (all 8 parameters described). Description goes beyond by explaining SoQL syntax with examples (e.g., 'crime_type, count(*)' for select) and clarifying _apiKey purpose.

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

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

Clearly states it runs raw SoQL queries against Austin open-data resources by Socrata ID. Verb+resource+scope are specific, and it distinguishes from sibling tools austin_datasets and austin_recent.

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

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

Explicitly mentions when to use (raw SoQL queries) and provides alternatives: 'Use austin_datasets to find a resource id, or austin_recent for the common ones.'

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, and non-destructive behavior. The description adds that results are returned newest-first, uses friendly names, and hints at API keys for rate limits. It complements annotations without contradiction, making behavior fully transparent.

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

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

The description is extremely concise: two sentences plus a list and a short instruction. Front-loaded with purpose, then usage guidance. Every sentence adds value, no waste. Optimal length for quick comprehension.

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

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

Complete for a simple list tool. Explains return order (newest-first), mentions filtering, and directs to sibling for complex queries. Despite no output schema, the description covers what the agent needs to know to use the tool correctly.

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

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

Schema coverage is 100% with all parameters described. The description adds minimal extra semantics beyond the schema, such as the enum values list and the where filter example. It does not deepen understanding of parameter usage significantly, meeting baseline but not exceeding.

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

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

The description clearly states the tool returns recent records from common Austin datasets by friendly name, avoiding need for Socrata IDs. It lists the exact dataset names and distinguishes itself from web search and the sibling tool austin_query, providing specific verb+resource+scope.

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

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

The description explicitly tells when to prefer this tool over web search and directs complex queries to austin_query. It provides concrete examples of use cases ('recent crime in Austin', etc.) and filters guide ('Add a SoQL where'), offering clear usage context 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 provide readOnlyHint, idempotentHint, etc. Description adds extensive behavioral details: resolution process, classifier fan-out, response shapes, safety mechanisms, resolution rules, fallback handling. No contradiction.

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

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

Very detailed but verbose; all information is valuable but could be structured better (e.g., bullet points or sections). Long paragraph may overwhelm, but each 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?

Comprehensive coverage: classifiers, fan-out examples, response shapes, error states (low confidence, closed markets), resolution rules, news fallback, tradeability warnings. No output schema, but return structure is explained in detail.

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: explains market input types (slug, URL, question), depth options, and include_raw behavior. Enhances understanding beyond schema.

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

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

Clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' Distinguishes from siblings like polymarket_edges and provides specific use cases ('should I bet on X', 'what does the data say about Y').

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 ('Use for...') and gives examples. Does not list alternatives or when not to use, but context from sibling tools implies differentiation. Good 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 declare readOnly, openWorld, idempotent. Description adds significant details: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), specific metrics (revenue, net income, cash, debt for companies; adverse events, approvals, trials for drugs), and handling of off-calendar fiscal years. No contradiction.

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

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

The description is concise and well-structured: front-loading the purpose with examples, then usage guidance, then details on data sources and results. Every sentence adds value with zero waste.

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

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

Despite no output schema, the description sufficiently explains return values: 'paired data + pipeworx:// citation URIs per entity'. It covers input constraints, behavior, sorting, and output format. Complete for a comparison tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context beyond schema: for 'type', it explains what data is pulled; for 'values', it clarifies tickers/CIKs for company and drug names. This extra context raises the score to 4.

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

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

The description clearly states the tool performs side-by-side comparison of 2–5 companies or drugs in one call, with specific verbs like 'compare', 'rank', 'head to head'. It distinguishes from single-entity lookups by its explicit multi-entity scope.

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 instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' It provides example queries and indicates when to use (comparison) and implicitly when not to (single entity).

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 discloses decomposition of questions into facets, parallel routing to 4,482 tools, return format (findings packet with evidence, confidence, source, citation, gaps[]), and expected response time (15-60s). Adds value beyond annotations (readOnlyHint, etc.) with no contradictions.

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

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

Description is verbose but well-structured: starts with critical account requirement, then main functionality, then usage guidance, then examples. Front-loaded key info. Slightly lengthy but justified for complexity.

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

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

Covers all needed aspects: account requirement, what it does, how it works (decomposition, parallel tools), return format, usage scenarios, limitations, and time expectation. No output schema but description compensates fully.

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

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

Schema has 100% coverage; description adds meaning by explaining depth enum values (quick=3, standard=5, thorough=8 paid) and that question accepts broad/multi-part input. Enhances understanding beyond schema alone.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1129 STRUCTURED data sources' and differentiates it from siblings like ask_pipeworx and open-web search. It provides specific use cases and examples.

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 this tool vs alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING... prefer ask_pipeworx'. Also notes account requirements and paid plan for 'thorough' depth.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds context by stating it returns 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and that 'each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations and provides valuable behavioral transparency.

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

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

The description is relatively long but efficiently packs key information: purpose, use cases, output format, and guidance on when to call. It is front-loaded with the core action and list of domains. While every sentence earns its place, minor trimming could improve conciseness.

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

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

Given the parameter count (6, with multiple aliases) and no output schema, the description explains the input comprehensively and describes the return format ('names, descriptions, and full input schemas (with curated examples)'). It also covers the tool's role in the tool ecosystem ('Call this FIRST'). This is fully complete for an exploration tool.

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

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

Schema description coverage is 100%, so baseline 3. The description adds meaning by providing examples of queries (e.g., 'look up FDA drug approvals') and mentioning that the tool accepts aliases (task, q, description, search). It also explains the limit parameter's default and maximum. This adds value beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It lists specific domains (SEC filings, financials, etc.) and contrasts with siblings by advising to 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This leaves no ambiguity about what the tool does and how it differs from siblings.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist for:' followed by a comprehensive list. It also provides a directive: 'Call this FIRST when you have many tools available and want to see the option set.' This gives clear guidance on 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds value by detailing the parallel fan-out across sources, the specific data returned, and the patent API sunset issue, providing behavioral context beyond what annotations provide.

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

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

The description is front-loaded with examples and contains rich, scannable information. While every sentence is valuable, it could be slightly more concise (e.g., the phrase 'fans out across' could be tightened), but it remains well-structured and efficient.

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

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

It thoroughly documents all return fields (cik, company_name, recent_filings with URIs, fundamentals, patents, news, LEI) and notes limitations (patent API sunset). With no output schema, this description is fully self-contained and provides complete context 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?

Despite 100% schema coverage, the description adds crucial meaning: it clarifies that 'value' accepts ticker or zero-padded CIK (not names), and that 'type' is currently only 'company'. This prevents misuse and compensates for any schema terseness.

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

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

The description explicitly states 'full cross-source profile of a US public company' and provides multiple example queries. It clearly distinguishes from sibling tools like resolve_entity and compare_entities, making the purpose unambiguous.

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

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

It provides explicit guidance: 'ALWAYS PREFER over chaining...' and specifies input formats (ticker or CIK) while advising to use resolve_entity for names. It also notes that patent API may soft-fail, setting expectations.

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

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

Annotations already provide destructiveHint=true and idempotentHint=true; description adds no new behavioral context beyond 'Delete'.

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, front-loaded sentences with zero waste.

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

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

Covers purpose, usage, and pairing; lacks hint about return value, but acceptable for a simple deletion tool.

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

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

Schema coverage 100% with clear parameter description; tool description does not add additional meaning beyond 'by key'.

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

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

States clear action 'Delete a previously stored memory by key'. Distinguishes from siblings '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 specifies when to use: when context is stale, task done, or clearing sensitive data. Pairs with related tools.

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

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

Annotations already signal readOnly, openWorld, idempotent, non-destructive. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' This goes beyond annotations without contradiction.

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

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

The description is two sentences long: a clear functional statement plus a bullet list of use cases. Every word adds value, no redundancy.

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

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

For a tool with 2 parameters, rich annotations, and no output schema, the description covers the core functionality, behavior, output format, and use cases. It is complete and self-contained.

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 (100% coverage). The description adds minor context like example URL format and default/max for max_links, but does not significantly extend schema meaning. 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: 'Generate a production-ready llms.txt file for any URL'. It specifies the output format, mentions target AI crawlers, and gives practical use cases. This distinguishes it from related sibling tools like ai_visibility_check or scan_competitor_ai_presence.

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 lists three concrete use cases: getting a client's site indexed, drafting for own project, or auditing competitor's AI visibility. It does not explicitly state when not to use, but the examples provide clear guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false. The description adds that it returns specific fields and defaults to active subscriptions, which is useful but not extensive.

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 filler. Each sentence adds value: first states purpose, second gives usage guidance.

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

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

For a simple list tool with full annotation coverage and one parameter, the description adequately covers return fields, default behavior, and purpose. No output schema exists, but the description lists the return fields.

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 descriptions. The description adds no new parameter info beyond clarifying the default behavior (active subscriptions) and implying the optionality of include_inactive.

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 exactly what the tool does: list the caller's active subscriptions, and specifies the return fields. It distinguishes from sibling tools like subscribe and unsubscribe.

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

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

Explicitly advises when to use: to review what you're monitoring before adding more or to find an id to cancel. This provides clear context and mentions alternative actions.

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 (non-readOnly, non-destructive), the description adds rate-limiting (5/day) and free usage (no quota). This fully discloses behavior, 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 front-loaded with the main purpose, followed by usage rules. It's informative but slightly verbose for a feedback tool. Could trim redundancy but 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?

Given no output schema and simple input, the description covers purpose, parameters, behavior, and constraints thoroughly. No gaps for an 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%. Description adds meaning: explains each 'type' enum, suggests message length (1-2 sentences, 2000 chars), and context's optionality. Adds value beyond schema.

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

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

The description clearly states it sends feedback to the Pipeworx team, listing specific types (bug, feature, data_gap, praise). The verb 'tell' and resource 'Pipeworx team' are specific. No sibling tool does this, so it's well-distinguished.

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: for bugs, missing features, data gaps, praise. Also gives when-not: don't paste user prompts. Includes rate limits and quota info. Provides clear context for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false. The description adds valuable context: caching (5min-1h depending on window), no PII, and that data is derived from CF analytics-engine. 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 at two paragraphs, front-loaded with the main purpose. Every sentence adds value: purpose, output, use cases, caching, privacy. No wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It explains what is returned (top tools, top packs, total call volume), the windows, caching, and use cases. No gaps evident.

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

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

Schema coverage is 100% with a description for the 'window' parameter. The description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This adds value beyond the schema's enum listing.

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

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

The description clearly states the tool returns trending data from other AI agents, specifying the output: top tools, top packs, and total call volume over configurable windows. It is distinct from siblings like ask_pipeworx or ask_pipeworx_grounded which focus on answering questions.

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

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

The description provides three explicit use cases (discovering hot data sources, confirming canonical tools, aligning use cases). It does not explicitly state when not to use or list alternatives, but the use cases are clear enough to guide selection.

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

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

Annotations (readOnlyHint, openWorldHint, destructiveHint false) are consistent. Description adds extensive detail: explains monotonicity checks, partition checks, semantic anchor, partition filter, fill check with live CLOB depth, and when not to trade. No contradiction.

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

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

Well-structured with key info upfront (requirement, modes). Detailed but focused; each section (semantic anchor, partition filter, fill check) adds value. Slightly long but efficient for the complexity.

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

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

Covers all aspects: modes, checks, response structure, fill check, related tool. Despite lacking output schema, description is comprehensive enough for an AI to correctly invoke and interpret results.

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 value by explaining accepted formats (slugs, URLs) and how each mode works (event walks child markets, topic searches related events). Baseline 3 raised due to added context.

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

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

Clearly states 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks' and distinguishes two modes (event and topic). Distinct from sibling tools like polymarket_edges and polymarket_fill_risk.

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

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

Explicitly says REQUIRES event or topic, recommends event for specific markets and topic for cross-event scanning, and mentions polymarket_fill_risk for custom sizing. Lacks explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds caching behavior ('Cached 1h at the KV level') and details of model families, filter knobs, and response structure, 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?

The description is verbose and lacks clear structure (single block of text). While every sentence adds value, it is not concise for an AI agent. Could benefit from bullet points or sections.

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

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

Despite no output schema, the description fully details the response structure (by_segment, diagnostics, per-opportunity fields), caching, filter knobs, and edge cases. Complete for a complex tool.

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

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

Schema coverage is 100% with detailed parameter descriptions. The description does not add per-parameter meaning but provides overarching context. 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 scans Polymarket markets for opportunities where Pipeworx data disagrees with market price, using specific model families. It distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx-based signals.

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

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

The description says it's built for 'what should I bet on today' and mentions tradeable-edge knobs, but does not explicitly contrast with sibling tools or state when not to use it. However, the context is sufficient for most agents.

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

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

Annotations indicate safe, idempotent, non-destructive behavior. Description adds limits (60-day TTL, non-intraday decay) and explains snapshot gaps, providing valuable behavioral context beyond annotations.

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

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

Well-structured with purpose first, then response details, then limits. Slightly verbose but every sentence is informative.

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

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

Comprehensive for a tool with no output schema. Explains inputs, outputs (tracked[], expired[], snapshot_dates[]), computation of trend/decay, and limitations.

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

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

Schema has 100% coverage. Description adds default values and usage context (lookback, snapshot family), which complements 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?

Description clearly states the tool's purpose: analyzing edge persistence and decay over time using daily snapshots. It distinguishes from siblings like polymarket_edges by focusing on time-series telemetry.

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?

Describes when to use (to assess edge aging) and provides context with the example of fresh vs. old edges. Does not explicitly state when not to use, but context is clear.

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

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

Beyond annotations (readOnlyHint, idempotentHint, destructiveHint=false), the description adds behavioral details like checking live CLOB depth, returning a verdict, and warning about forced directional risk. No contradiction.

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

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

The description is long but well-structured with clear sections for single-market and basket modes. Every sentence adds value, though slightly verbose; could be more concise without losing detail.

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

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

For a 4-param tool with no output schema, the description explains return fields (top_of_book, vwap_fill_price, verdict, etc.) and edge cases like thin_legs and forced directional risk. Complete for its complexity.

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

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

Schema description coverage is 100%, and the description adds context like defaults (side, size_usd), interpretation (settlement notional for basket), and mode-specific behavior, providing 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 between single-market and basket modes, and is differentiated from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' Also explains when not to use, e.g., theoretical edge on thin books is not capturable, and consequences of partial fills.

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

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

Adds significant behavioral context beyond annotations: two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explanation of when spreads are meaningful. Annotation contradiction is 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?

The description is information-dense with well-structured sections (modes, response, safety). Every sentence adds value, although slightly long. Could separate response format for clarity, but overall effective.

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

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

Given complexity (cross-venue, two modes, safety checks), the description is thorough. Explains when spreads are valid, output meaning, and each safety field. No output schema, but description compensates fully.

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

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

Schema coverage is 100%. Description adds meaning beyond schema by explaining two modes and how explicit parameters override topic-mapped sides, plus examples. Baseline 3, plus 1 for added context.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It uses specific verb+resource: 'Cross-venue spread', and distinguishes from siblings like single-venue arbitrage or edge 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?

Describes two modes (topic shortcuts vs explicit pairings) and when to use each. Warns that most pre-mapped topics return compatibility_warning, implying limited tradeability. However, it does not explicitly contrast with sibling tools like polymarket_arbitrage.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds context about scoping (to identifier) and typical use cases but does not introduce additional behavioral traits beyond what annotations imply.

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

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

The description is concise with four sentences, each serving a distinct purpose. It is front-loaded with the core action and efficiently includes usage context, scoping, and pairing with sibling tools, leaving 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 the single optional parameter, absence of output schema, and sufficient annotations, the description fully covers the tool's behavior, scope, and relationship to sibling tools. It provides all necessary information for an agent to use the tool correctly.

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

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

Schema coverage is 100%, and the description aligns with the parameter description for 'key' from the schema. The description adds practical context (listing all keys when omitted) but does not provide new semantic meaning beyond the schema's existing 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 explicitly states it retrieves a value saved via remember, or lists all keys if omitted. It distinguishes from sibling tools (remember, forget) and clearly communicates the resource (saved memory) and action (retrieve/list).

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

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

The description provides clear context for when to use the tool (look up stored context like user's target ticker or research notes) and implies when not to use it (avoid re-deriving information). It pairs with remember and forget, offering a complete workflow without explicit alternatives.

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

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

Annotations already indicate non-destructive, read-only, idempotent behavior. Description adds that each event carries source, citation_uri, and raw payload, and explains the effect of mark_read on subsequent calls.

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?

Every sentence adds value: main purpose, return fields, filtering, mark_read behavior, polling, alternative access. No unnecessary 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?

Explains return fields despite no output schema. Covers filters, mark_read, polling, and alternative access. Missing pagination details for limit parameter, but otherwise 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 all 5 parameters with descriptions. The tool description adds context like the effect of mark_read on feed state and example filter values, improving usability beyond schema alone.

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

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

The description clearly specifies the tool pulls fired events from the subscription feed, naming the resource (fired events) and the action (pull). It distinguishes from siblings like 'list_subscriptions' which list subscriptions, not events.

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

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

It states when to use (to get recent alerts) and provides filtering guidance (type, since). It suggests polling works fine and mentions an alternative access method, but does not explicitly exclude other usage scenarios.

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

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

Beyond the annotations (readOnly, idempotent, etc.), the description adds significant behavioral context: the parallel fan-out to multiple APIs, fallback mechanism, window format acceptance, and soft-failure of USPTO. No contradictions with annotations.

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

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

The description is a single, dense paragraph that front-loads usage examples and clearly states the tool's function. Every sentence adds value, and there is 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?

Given the complexity (multiple sources, fallbacks, parameter options) and lack of output schema, the description thoroughly covers return structure (changes[] grouped by source, total_changes count, citation URIs) and provides complete guidance for invocation.

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

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

The description adds meaningful details beyond the input schema: explains 'type' is limited to 'company', 'since' accepts ISO dates or relative shorthands with examples ('7d', '30d', '3m', '1y'), and 'value' can be ticker or CIK. It also recommends '30d' or '1m' for typical monitoring.

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

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

The description clearly states the tool's purpose: a change feed for a company over a specified time window, fanning out to multiple sources like SEC EDGAR, GDELT/GNews, and USPTO. It distinguishes itself from the sibling 'entity_profile' tool, which provides static profiles.

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

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

The description provides explicit usage patterns ('What's new with X', 'latest on Y') and specifies when to use the alternative tool 'entity_profile' for static profiles. It also explains fallback behavior between GDELT and GNews, guiding proper invocation.

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

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

Annotations indicate idempotentHint=true and destructiveHint=false. The description adds key behavioral details: storage as key-value pairs scoped by identifier, and retention policies (persistent for authenticated, 24-hour for anonymous). This enriches transparency beyond annotations without contradiction.

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

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

The description is four sentences, front-loaded with purpose, then usage, then behavioral details. Every sentence adds value with no redundancy or filler, making it highly efficient.

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

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

The tool is simple (2 string params, no output schema). The description covers purpose, usage, persistence, and sibling relationships. It omits return behavior, but given the simplicity and annotations, it is nearly complete, scoring a 4.

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 enriches both parameters with examples ('subject_property', 'target_ticker') and clarifies value as 'any text'. This adds practical meaning, justifying a score of 4.

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

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

The description uses the verb 'save' and specifies the resource as 'data the agent will need to reuse later', clearly defining the tool's purpose. It distinguishes from siblings like 'recall' and 'forget' by stating the action and scope (across sessions).

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 when-to-use guidance ('when you discover something worth carrying forward') with concrete examples. It also contrasts with 'recall' and 'forget', and details retention differences for authenticated vs anonymous users, offering clear context for selection.

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

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

The description adds behavioral context beyond annotations, e.g., cascading through several lookup endpoints internally and replacing 2-3 manual lookups. Annotations already indicate read-only, idempotent, non-destructive. Missing explicit error handling or failure cases.

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, well-structured, and front-loaded with examples and purpose. Every sentence adds value without redundancy.

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

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

Given only two parameters and no output schema, the description covers input examples, output structure, and internal cascading. It lacks error handling or what happens on failed resolution, but is otherwise comprehensive.

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

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

The description enriches parameters with examples (e.g., for company: AAPL, 0000320193; for drug: ozempic, metformin) and explains the output structure for each type, including citation URIs. Schema coverage is 100% and the description adds significant value.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers needed by other tools. It uses specific examples and distinguishes itself as the first step for name-to-ID conversion.

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

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

The description explicitly says 'Use FIRST whenever you have a name but need an ID' and lists supported types. While it doesn't explicitly mention when not to use it, the context is clear. It could be improved by noting that if you already have an ID, you don't need this tool.

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

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

Annotations indicate read-only, idempotent, non-destructive behavior. The description adds that the tool internally calls ai_visibility_check for each entity and ranks them, which provides useful behavioral context beyond annotations. 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 two sentences plus an example, front-loaded with purpose and key detail. Every sentence adds value without redundancy.

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

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

The description explains the output (ranked list with score, confidence, signal density) despite no output schema. It covers all parameters (all documented in schema) and gives a realistic usage scenario. Slightly lacking in return format details but sufficient given tool 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%, so baseline is 3. The description adds meaning for the 'entities' parameter: first entity is treated as 'subject' for narrative, rest as competitors. This goes beyond schema documentation.

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

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

The description clearly states the tool compares AI visibility across multiple entities side-by-side, probes each entity using ai_visibility_check, and ranks results. It distinguishes from the sibling ai_visibility_check by emphasizing multi-entity comparison.

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

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

The description provides a concrete use case ('competitive AI-marketing audits') with an example query. It does not explicitly state when not to use the tool or mention alternatives, but the context implies it is for multi-entity comparisons.

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 readOnlyHint=true, so no mutation concern. The description adds rich behavioral detail beyond annotations: partial failures degrade gracefully, bundlephobia first measurement takes 5-30s, sources_failed will list timeouts. It also describes the return structure (summary, advisory detail, links, alternatives). 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 mostly concise with two sentences, but the first sentence is very long (wraps multiple sub-clauses). It front-loads the purpose and efficiently lists return fields. A small readability improvement would push this to 5.

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 (composite check across two external services, partial failures, timing), the description is thorough. It covers the return format (summary block, per-advisory detail, links, alternatives), scope (npm only), and graceful degradation. No output schema exists, but the description lists the return fields adequately.

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

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

Schema coverage is 100% (both parameters described). The description's first sentence implies the parameters' role in the composite call but does not add new semantic meaning beyond what the schema already provides (package name, version default). A 3 is appropriate when schema already carries the load.

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

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

The description opens with a clear verb+resource: 'Composite should I add this npm package to my project check in ONE call'. It specifies the exact purpose (checking safety, popularity, size) and distinguishes from sibling tools by naming the external sources (deps.dev, bundlephobia) and noting the npm-only scope.

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: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides exclusion criteria: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This helps the agent choose the right tool.

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds significant behavioral details beyond annotations: embedding model (BGE-base-en), similarity metric (cosine), window size (500-char overlapping), character cap (200K chars) with truncation and flagging behavior. This fully informs the agent of runtime behavior.

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

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

The description is concise (5 sentences) and well-structured: purpose, usage, technical details, pairing with sibling, and implementation details. Every sentence adds essential information with no redundancy. It is front-loaded with the core idea.

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

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

For a tool with no output schema, the description decently covers return structure (passages, offsets, scores) and truncation behavior. It also mentions the pairing with a sibling. However, it could more explicitly describe the output format (e.g., array of objects with fields) for full completeness. Still, it provides sufficient context for an 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% with descriptions. The tool description adds context: explains that 'text' is the document to search, 'query' is natural language with examples, and 'limit' is max passages with default. It also adds the 200K char cap for text, which is not in the schema. This adds value beyond the schema, justifying a 4.

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

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

The description clearly states the verb ('Semantic search INSIDE a fetched record'), the resource ('the text you already pulled'), and the result ('top-N passages with character offsets and similarity scores'). It distinguishes from sibling tools by specifying it is for internal search within a fetched record, not for external search or other operations.

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

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

The description provides explicit guidance: 'Use when the record is too big to cram into the prompt' and pairs with ask_pipeworx_grounded. It explains when to use but does not explicitly state when not to use it, e.g., for small texts. This is good but could be slightly more complete.

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 claims this tool creates a new subscription and returns a new ID each time, implying it is not idempotent. However, annotations set idempotentHint=true, which indicates the operation should have no side effects when called multiple times. This contradiction is a serious flaw, making the description misleading about the tool's behavior.

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 front-loads the purpose and is efficient with information, but it is a single dense paragraph that could benefit from structured formatting (e.g., bullet points or separate sections for types and delivery). Still, 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 the tool's complexity (3 params, nested objects, no output schema), the description covers the return value, type-specific parameters, delivery options, and prerequisites. It does not mention duplicate subscription handling, but overall it is quite comprehensive.

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

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

Schema coverage is 100%, and the description adds substantial value by explaining each parameter with concrete examples (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}'), clarifying delivery constraints (e.g., SMS day cap), and detailing webhook HMAC signing. This goes well beyond the schema descriptions.

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

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

The description starts with 'Create a proactive monitoring subscription to a live-data event stream. Returns the new subscription id.' This clearly specifies the verb (Create) and the resource (subscription to an event stream), distinguishing it from sibling tools like unsubscribe 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?

The description states prerequisites (Pipeworx OAuth account, not for anonymous/BYO) and provides detailed examples of supported subscription types and delivery channels. It does not explicitly mention when not to use this tool versus 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 indicate readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: it is an onboarding entry point, returns category-bucketed example questions, and draws from a live catalog. 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 front-loaded with the core purpose, then provides details. Every sentence adds value, and it is appropriately sized for the complexity.

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

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

Given no output schema, the description explains what is returned (category-bucketed example questions with exact tool+argument shape). It is complete for an onboarding tool, covering use case, arguments, and output nature.

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

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

The schema covers the single parameter with 100% coverage and a clear description. The description adds further context by explaining the purpose of the topic parameter ('to focus') and listing possible values, which is helpful but not critical.

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

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

The description clearly states that this tool returns category-bucketed example questions for a Pipeworx agent, acting as the onboarding entry point. It uses specific verbs like 'returns' and 'use this FIRST', and distinguishes from sibling tools by being the introductory tool to understand Pipeworx's capabilities.

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

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

The description explicitly says when to use it ('Use this FIRST when you do not yet know what Pipeworx can do for you') and provides guidance on arguments: omit for full spread, pass topic to focus. It also mentions learning how to call meta-tools, implying 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?

Adds behavioral details beyond annotations: soft delete (deactivated not deleted), ownership enforcement, and preservation of historical events. No contradiction with annotations.

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

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

Three concise sentences, each adding value: action, constraint, effect. No wasted words.

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

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

Covers key behavioral aspects (ownership, soft delete, history) but lacks mention of error handling (e.g., invalid id) or return value.

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 the single parameter. Description adds context that the id comes from 'subscribe', which is helpful.

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 'Cancel a subscription by id' with specific verb and resource. Distinguishes from sibling tools 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?

Explicitly mentions ownership enforcement ('you can only cancel your own subscriptions') and that the row is deactivated not deleted, guiding when to use and what to expect.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds significant behavioral context: it returns a verdict with specific categories (confirmed, approximately_correct, refuted, inconclusive, unsupported), a structured form, actual value with citation, and percent delta. It also notes that it replaces 4–6 sequential calls, providing efficiency insight. No annotation contradiction.

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

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

The description is concise and well-structured. It front-loads with synonyms for the tool's use, then gives usage guidance and specific details about supported claims and output. Every sentence is informative, and there is no fluff.

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

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

Despite having no output schema, the description fully explains the return values (verdict categories, structured form, citation, percent delta). It also specifies the domain limitation and how the tool replaces multiple sequential calls. For a single-parameter tool, this is highly 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% for the single parameter 'claim', which already has a description with examples. The tool description does not add further parameter-level details beyond that. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: natural-language claim verification against authoritative sources. It provides specific examples of user prompts ('Is it true that...', 'fact check') and explicitly describes the supported domain (company-financial claims for US public companies via SEC EDGAR + XBRL). This specificity distinguishes it from sibling tools like 'deep_research' or '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 includes a clear usage guideline: 'Use whenever the agent needs to check whether something a user said is factually correct.' It implies the tool is specialized for financial claims but doesn't explicitly exclude other contexts. The description does not mention alternatives among siblings, but the domain is specific enough to guide appropriate use.

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