swisstransport

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context: default model is free, Anthropic requires BYO key, returns per-model and combined view, and passes API key directly to api.anthropic.com. This goes beyond annotations without contradicting them.

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

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

The description is three sentences with no redundancy. It front-loads the core action and outcome, and every sentence adds distinct value: purpose, default model, return structure, use cases.

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

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

Given the tool has no output schema, the description adequately lists return fields (per-model {score, confidence, signals, raw_response} + combined view). It covers input, default/paid options, and use cases. Annotations provide safety guarantees, so no additional behavioral notes are needed.

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% parameter description coverage. The description adds extra meaning: default model is Workers AI Llama-3.3-70b (free), _apiKey is passed straight through to api.anthropic.com, and context is for disambiguation. This enriches the schema's detail.

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

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

The description uses a specific verb ('Probe one or more LLMs') and clearly identifies the resource ('what they know about a business / brand / product / topic') and outcome ('score visibility 0-100 per model'). It distinguishes from siblings like 'scan_competitor_ai_presence' by emphasizing general entity probing vs. competitor-specific scans.

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

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

The description states explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains when to provide an API key for paid models. However, it does not explicitly mention when not to use this tool or compare it directly to siblings like 'scan_competitor_ai_presence'.

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

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

Annotations already mark it as read-only, non-destructive, idempotent, and open-world. The description adds that it routes to 3,745 tools and returns structured answers with stable pipeworx:// citation URIs, which are useful behavioral details beyond the annotations. 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 a strong opening directive, followed by domain list, mechanism, and usage patterns. Could be slightly shorter, but every sentence adds value. Front-loaded with the most important 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?

Given the tool's complexity (routing to many sources), the description covers purpose, usage, and behavior adequately. No output schema exists, but the description mentions structured answers with citations. It could detail output format, but it's not essential for agent invocation.

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

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

Schema has 6 parameters (all aliases for the question) with 100% coverage. The description adds that the parameter accepts natural language, provides examples, and lists aliases. This clarifies the free-form nature of the input beyond the schema's enumerations.

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 routes natural language questions to a vast set of structured data sources, covering many domains. It uses specific verbs ('ask', 'routes') and resources ('Pipeworx', '3,745 tools'). It distinguishes from web search and implicitly from siblings like ask_pipeworx_grounded by emphasizing its breadth.

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 'PREFER OVER WEB SEARCH' and lists many example queries and domains. Provides trigger phrases like 'what is', 'look up', 'current'. However, it does not explicitly state when NOT to use it or compare with sibling tools such as ask_pipeworx_grounded or deep_research.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it extracts answer only from tool result, returns explicit refusal reasons (not_in_source, etc.), and costs one extra LLM call. No contradiction.

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

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

Two paragraphs, front-loaded with key purpose and behavior. Dense but every sentence adds value. Slight improvement possible in brevity.

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

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

Given complexity (routing to many sub-tools) and absence of output schema, description fully covers behavior, return format (explicit refusals), and cost trade-off. Complete for high-stakes use.

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

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

Schema coverage is 100% with all 6 parameters being aliases for 'question'. Description does not add additional meaning beyond what the schema already provides for parameters.

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

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

Description clearly states it is a hallucination-resistant answer mode for high-stakes reads, distinct from the sibling ask_pipeworx. It specifies verb (extract answer) and resource (pipeline of 3,745 tools across 884 sources).

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

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

Explicitly states when to use: when answer will be quoted, cited, or acted on, and must not invent facts (financial, legal, medical, public statements). Also advises preferring ask_pipeworx for casual lookups due to extra cost.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint as true and destructiveHint as false, which the description fully supports. It details the tool's behavior: resolution classification, fan-out to data sources, response shapes, safety short-circuits (low-confidence, closed markets, wide spreads), and cancellation rule parsing. No contradictions.

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

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

The description is long but well-structured with labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.). It front-loads the core purpose. While comprehensive, it could be slightly more concise by trimming redundant examples, but the detail is valuable for an AI agent.

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

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

Given the tool's complexity, no output schema, and rich input schema, the description is remarkably complete. It covers input variations, output structure (market, analysis, evidence), edge cases, safety mechanisms, resolution rules, cancellation risk, and even response size considerations. No gaps.

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

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

With 100% schema coverage, the description still adds value by explaining each parameter's impact: depth defaults to thorough, market input types with examples, include_raw default false with recommendation. This goes beyond what the schema provides.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data, with specific examples of inputs and outputs. However, it does not explicitly distinguish this tool from sibling tools like polymarket_edges, which also deal with edge analysis, though the scope is broader.

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

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

The description provides explicit use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), input types, and warnings about confidence levels, closed markets, wide spreads, and cancellation rules. It tells the agent when to trust the analysis and what to inspect, offering excellent 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 openWorldHint. The description adds critical behavioral context: it handles off-calendar fiscal years correctly, sorts results by primary metric, and returns paired data with citation URIs. This goes beyond annotations, providing full transparency.

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

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

The description is well-structured and front-loaded with example queries, but it is somewhat long. While every sentence adds value, it could be slightly more concise. However, it effectively uses emphasis and clear 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?

Given the complexity of two entity types with different data sources, the description completely covers what data is fetched, how results are sorted, and the output format (paired data + citation URIs). No output schema exists, so the description adequately fills that gap.

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

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

Schema coverage is 100%, but the description adds significant meaning beyond the schema. It explains that type='company' pulls specific financial data from SEC EDGAR/XBRL, while type='drug' pulls FAERS data, and details the format of values (tickers/CIKs for companies, names for drugs). This enriches 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 performs side-by-side comparison of 2-5 companies or drugs in a single parallel call. It provides example queries, explains what data is returned for each type, and explicitly distinguishes from sequential single-entity lookups, 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?

The description explicitly advises to 'ALWAYS PREFER over sequential single-pack lookups' when comparing entities, giving clear usage context. It provides example natural language triggers, indicating exactly when to invoke this tool.

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

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

Annotations already provide readOnlyHint etc., but description adds critical behavioral details: never invents facts, includes gaps array, expects 15-60s response time, and requires authentication. 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 relatively long but every sentence adds essential information: purpose, process, usage guidance, prerequisites, and output format. It is well-structured and front-loaded with the core value proposition.

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

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

Despite no output schema, the description thoroughly explains what the agent receives (structured findings packet with evidence, gaps, sources) and what is required (account, plan). It covers all necessary context for invocation and decision-making.

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

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

Schema coverage is 100%, and description adds value by mapping depth values to specific numbers (quick=3, standard=5, thorough=8) and noting paid requirement for thorough. Question description clarifies broad questions are acceptable.

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 'Grounded multi-source research in ONE call' with decomposition and parallel routing. It distinguishes itself from sibling tool 'ask_pipeworx' which is for single lookups.

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

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

Explicitly says to use for broad/multi-part questions and directs to ask_pipeworx for single lookups. Also mentions prerequisites: Pipeworx account 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 declare readOnlyHint=true and idempotentHint=true. Description adds context about output (returns top-N tools with names, descriptions, schemas, curated examples) and behavior (search, no side effects). 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?

Single paragraph, front-loaded with purpose, then usage, then output. Every sentence adds value. No wasted words.

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

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

Given complexity of discovery tool with many siblings, description covers purpose, when to use, output format, and examples. No missing critical info. Output schema not needed as description explains return structure.

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

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

Schema coverage is 100%, baseline 3. Description adds value by clarifying aliases ('Accepts task, q, description, search as aliases') and providing examples, raising it 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?

Clear verb 'Find tools by describing the data or task', specifies resource (tools) and distinguishes from sibling tools which are specific tools like deep_research or compare_entities.

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 'Call this FIRST when you have many tools available and want to see the option set (not just one answer)', provides examples of tasks, and implies when not to use.

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

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

Annotations already indicate readOnly, openWorld, idempotent, non-destructive. The description adds critical context: the tool fans out across multiple sources, returns up to 5 filings with URIs, fundamentals sorted by period_end descending, patent source soft-fail, news fallback, and LEI. This greatly exceeds what annotations alone convey.

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

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

The description is dense but front-loaded with user query examples that quickly convey intent. It is structured as a single paragraph mixing usage, behavior, and return details. While highly informative, it could be slightly more organized, but every sentence earns its place.

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

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

Given the tool's complexity (multiple data sources, no output schema), the description provides a complete picture: lists all return fields (CIK, filings with format, fundamentals sorted, patents, news, LEI), mentions limitations (patent sunset), and explains input constraints. No gaps for proper agent invocation.

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

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

Schema coverage is 100% and schema descriptions already explain parameters. The description adds value by clarifying that type is limited to 'company' (person/place coming soon), value must be ticker or zero-padded CIK, and names are unsupported. This is helpful but not essential given 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 uses multiple concrete examples ('Tell me about X', 'research Acme', etc.) and clearly states the tool provides a 'full cross-source profile of a US public company'. It distinguishes from sibling 'resolve_entity' by noting names are not supported. The verb 'profile' plus specific resources (SEC, XBRL, news) make 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?

Explicitly states 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view', providing a clear when-to-use directive. Also specifies when not to use: 'names not supported (use resolve_entity first if you only have a name)'. This eliminates ambiguity.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. Description simply says 'Delete', which aligns but adds no additional behavioral context like what happens on missing key or required permissions.

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, 33 words, front-loaded action. No filler.

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

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

For a simple tool with one parameter, no output schema, and informative annotations, the description covers usage, purpose, and pairing sufficiently.

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

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

Schema coverage is 100% with one param 'key' described as 'Memory key to delete'. Description adds no extra meaning beyond schema.

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

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

Clearly states verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings (remember, recall) explicitly.

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

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

Provides explicit when-to-use: 'when context is stale, the task is done, or you want to clear sensitive data'. Also recommends pairing with remember and recall.

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, idempotentHint, and non-destructive behavior. Description adds process details (fetches page, extracts info, emits markdown) and output format, 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?

Three sentences, front-loaded with main action, no redundant information. Every sentence adds value: purpose, process, and use cases.

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 tool with two parameters, no output schema needed, and annotations covering safety. Describes what it does, how it works, and what the output is. No gaps.

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

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

Schema coverage is 100% with clear parameter descriptions. The description does not add new semantic meaning beyond the schema, but it implicitly relates url to the URL of the site. 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 generates a production-ready llms.txt file for any URL, specifying its purpose for AI crawlers. It distinguishes from siblings like scan_competitor_ai_presence by focusing on file generation rather than analysis.

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

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

Provides explicit use cases: getting a client's site indexed, drafting for own project, auditing competitor visibility. Does not include when-not-to-use or alternatives, but no direct sibling alternative exists, making it sufficient.

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 the behavioral detail 'Returns up to the requested number of next departures', clarifying limit and the recency of results. 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?

Two short sentences, no wasted words, front-loaded with the core action. Every sentence adds value without redundancy.

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

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

Given the tool's simplicity, complete schema with examples, robust annotations, and existence of an output schema, the description covers all essential aspects. It does not need to explain return format as that is covered by the output schema.

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

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

Schema coverage is 100% with parameter descriptions. The description adds context beyond the schema by specifying 'Swiss locations' and explaining that the limit controls 'next departures', providing additional meaning for parameter usage.

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

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

The description clearly states 'Get public transport connections between two Swiss locations', specifying a clear verb and resource with geographic scope. It distinguishes from sibling tools like get_stationboard (which focuses on a single station) by emphasizing the 'between two Swiss locations' aspect.

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

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

The description implies usage for finding connections between two points, but does not explicitly state when to avoid this tool (e.g., for a single station's board, use get_stationboard). No alternatives are mentioned. Guidance is adequate but not explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the board is 'live', implying real-time data, but does not elaborate on caching, update frequency, or error behavior. Minimal added value beyond annotations.

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

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

The description is a single 10-word sentence that is front-loaded and contains no unnecessary words. It efficiently conveys the core purpose.

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

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

Given the simple tool, good annotations, and presence of output schema, the description is adequate. It covers the purpose and geographic scope (Swiss) which is important context. However, it does not mention any limitations or prerequisites.

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

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

Schema coverage is 100% for both parameters (station and limit), with descriptions in the schema. The tool description does not add any additional meaning or context for the parameters beyond what the schema provides.

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

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

The description clearly states the tool gets a live departure board for a Swiss public transport station. It specifies the resource (departure board) and scope (Swiss public transport), distinguishing it from siblings like get_connections and search_stations.

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 (when you need live departures for a station), but does not explicitly mention when not to use it or suggest alternatives. The sibling tools imply other functions, but no exclusions are stated.

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 aligns with annotations (readOnlyHint, idempotentHint, destructiveHint=false) by stating it lists subscriptions. It adds value by listing return fields, but does not disclose any additional behavioral traits beyond annotations.

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

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

Two concise sentences: first states purpose and return fields, second provides usage guidance. No wasted words and front-loaded with 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?

The tool is simple (one optional parameter, no output schema). The description covers purpose, return data, and usage context. Annotations provide safety profile. Complete enough for an agent to decide when to use this tool.

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

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

Schema has 100% coverage with description for the single optional parameter (include_inactive). The tool description does not mention the parameter, so it adds no meaning beyond the schema. Baseline 3 is appropriate.

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

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

Clearly states the tool lists the caller's active subscriptions and enumerates the return fields (id, type, params, etc.). The verb 'list' and resource 'subscriptions' are explicit, and the title matches.

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

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

Provides specific guidance: use to review monitoring before adding more subscriptions or to find an ID for cancellation. Does not explicitly name alternatives, but siblings include subscribe and unsubscribe, implying when not to use.

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

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

Annotations provide no destructive hint, read-only hint, etc. The description adds useful behavioral context: rate-limited to 5 per identifier per day, free, doesn't count against tool-call quota, and the team reads digests daily and signal affects roadmap. This goes beyond what annotations offer.

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

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

The description is well-structured and front-loaded with purpose. Every sentence adds value: usage triggers, anti-patterns, rate limits, quota impact. No fluff or redundancy. 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?

For a simple feedback submission tool, the description is complete. It covers purpose, usage scenarios, constraints (rate limits, quota), and what not to do. No output schema is needed, and the description provides all necessary context.

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

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

Schema coverage is 100% with each parameter described. The description adds further guidance: elaborates on type enum values (e.g., 'bug = something broke or returned wrong data'), specifies message length as '1-2 sentences typical', and instructs to describe issues in terms of Pipeworx tools/packs. This adds meaning beyond schema.

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

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

The description clearly states the tool's purpose: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific verbs (tell, send feedback) and identifies the resource (Pipeworx team). Among the sibling tools, it is the only one for sending feedback, so it is 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?

The description explicitly outlines when to use the tool: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a negative guideline: 'don't paste the end-user's prompt.' This gives 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, openWorldHint, idempotentHint, and non-destructive. The description adds valuable details: data source (CF analytics-engine), no PII, and caching behavior (5min-1h). This goes beyond annotations without contradiction.

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

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

The description is concise with no fluff. It front-loads the purpose, then covers use cases, data source, and caching. Every sentence adds value, achieving high density of information.

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

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

For a simple tool with one parameter, the description covers purpose, usage, transparency, and parameter semantics adequately. It mentions return contents (top tools, packs, volume) which is sufficient given no output schema.

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

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

The sole parameter 'window' has 100% schema coverage with an enum and description. The description supplements by explaining the effect of short vs long windows on recommending strategy, adding meaning beyond the schema.

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

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

The description clearly states the tool returns top tools, top packs, and total call volume over recent windows. The opening sentence 'What other AI agents are calling on Pipeworx right now' immediately conveys the purpose, and it is well-differentiated from siblings like discover_tools which lists all tools.

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

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

Explicitly lists three use cases for using the tool, providing clear context. However, it does not specify when not to use it or mention alternatives such as discover_tools, which would strengthen 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?

The description discloses extensive behavioral details: required inputs, internal checks (monotonicity, partition sum, Jaccard similarity, placeholder filter), fill check against live CLOB depth, and output structure. This goes well beyond the readOnlyHint and idempotentHint annotations, providing complete 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 well-structured with clear headings (REQUIRES, event mode, topic mode, SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the essential requirement. Every sentence provides necessary detail without redundancy, balancing completeness with readability.

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

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

Given the tool's complexity (two modes, multiple checks) and no output schema, the description fully explains the output (opportunities[], partition_check, fill_check), error conditions (no args fail), and edge cases (placeholder slugs, low similarity). It also references related tools for deeper needs, making it 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?

Both parameters are 100% covered in the schema with descriptions, but the description adds rich meaning: explains the two modes, provides example values (slug, seed question), and details how each mode behaves (walking child markets vs. cross-event scanning), greatly enhancing understanding.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks, distinguishes between two modes (event and topic), and explicitly mentions sibling tools like polymarket_fill_risk for customization, making the purpose highly distinct.

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 that one of `event` or `topic` is required, provides recommendations for each mode, warns against calling with no args, and directs users to polymarket_fill_risk for custom sizing, offering clear when-to-use and when-not-to-use guidance.

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

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

Adds significant value beyond annotations: caching details (1h KV), 24h-move warning, Fed bets note, and detailed segment behavior (e.g., partition_overround structure, placeholder-slug filter). Annotations already indicate read-only, idempotent, open-world.

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 long description (over 200 words) despite front-loading purpose. Contains extensive detail that is useful but could be more concise. Well-structured with clear 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?

Given 9 parameters, no output schema, and tool complexity, the description covers output structure (by_segment, diagnostics), edge calculation details, filter knobs, and caching. Complete for agent understanding.

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

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

100% schema coverage; description provides rich additional context for each parameter, e.g., min_kelly explains 'Skips opportunities that are too small to bet sensibly' and max_spread_pp 'anything wider eats most plausible edges'.

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

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

Clearly states the verb 'scan' and resource 'Polymarket markets', with specific output 'opportunities where Pipeworx data disagrees with market price'. Distinguishes from siblings like polymarket_arbitrage by focusing on data disagreement.

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

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

Explicitly says 'Built for "what should I bet on today"' and explains when to use it, including tradeable-edge knobs and diagnostics for empty segments. Does not contrast directly with siblings but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds rich behavioral details: snapshot TTL, decay computation on absolute edge_pp_net, response structure (tracked, expired, snapshot_dates), and interpretation of gaps. No contradictions.

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

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

The description is informative but slightly long. It front-loads the core question and then details response fields and limits. Every sentence adds value, though structure could be more streamlined.

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 (historical edge evolution) and lack of output schema, the description thoroughly covers return values (tracked, expired, snapshot_dates), their fields (trend, decay, lifespan_days), and limitations (TTL, snapshot gaps). No missing crucial context.

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

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

Schema description coverage is 100%, so baseline is 3. The description repeats parameter defaults and constraints but adds no new semantic meaning beyond what the schema already provides.

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

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

The description starts with a clear verb-resource combination: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It distinguishes itself from the sibling 'polymarket_edges' by focusing on historical persistence and decay rather than current edge values.

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 usage context with limits (60-day TTL, daily closes not intraday) and implies when to use (historical tracking) versus other tools like polymarket_edges. However, it does not explicitly state when not to use or list alternatives, leaving a slight gap.

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 include readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds behavioral detail: it walks the ladder, returns specific verdicts (clean|degraded|cannot_fill), identifies thin_legs, and explains forced_directional_risk. No contradiction with annotations.

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

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

The description is well-structured with clear sections (REQUIRES, SINGLE-MARKET, BASKET, USE THIS) and dense with information. While somewhat verbose, every sentence contributes value given the tool's complexity. Minor redundancy could be trimmed.

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 (4 params, no output schema), the description is comprehensive. It covers both modes, all return fields (including thin_legs, forced_directional_risk, etc.), usage guidance, and behavioral notes. The absence of an output schema is compensated by detailed return descriptions.

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

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

Schema description coverage is 100% and the description adds further meaning: it explains that size_usd is settlement notional in basket mode and side auto-defaults based on partition sum. It clarifies max spend vs target proceeds for single-market mode, enhancing understanding 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, explicitly separates single-market and basket modes, and lists specific outputs like top_of_book, vwap_fill_price, slippage_pp, etc. This makes the tool's purpose unambiguous and distinct from siblings.

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

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

The description explicitly states when to use this tool: before acting on polymarket_arbitrage SELL/BUY-EVERY-LEG signals or polymarket_edges trades above ~$500. It also warns about non-capturable theoretical overround on thin books and the risk of partial basket fills creating unhedged directional positions, providing clear exclusions and context.

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

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

The description provides extensive behavioral context beyond the annotations, including two modes, safety fields (compatibility_warning, temporal_alignment, skipped counters), and explanations of when spreads are meaningful. 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 thorough and front-loaded, but slightly verbose. Every sentence adds value, but some detail could be condensed without losing clarity.

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

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

Given the tool's complexity and lack of output schema, the description fully explains response fields, safety checks, and limitations. It covers all necessary contextual information for correct usage.

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

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

The description adds significant meaning beyond the schema, explaining how topic vs explicit parameters work, overrides, and interactions. Examples are provided, and all schema properties have descriptions.

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

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

The description clearly identifies the tool as computing cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying two modes (topic and explicit) and how the spread is calculated. This distinguishes it 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?

The description explicitly states when to use the tool (to find spreads) and when not to, based on compatibility_warning and temporal_alignment fields. It warns that most pre-mapped topics return warnings, guiding appropriate usage.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds useful context about scoping (anonymous IP, BYO key hash, account ID) beyond what annotations provide. No contradiction.

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

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

Two sentences, front-loaded with the core purpose, no unnecessary words. 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?

For a simple read-only tool with good annotations, the description covers purpose, usage, and parameter behavior. No output schema but return values are implied. No gaps identified.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning: 'omit the key argument to list all keys', explaining the behavior of the optional parameter beyond the schema.

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

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

The description clearly specifies the verb ('retrieve' or 'list') and the resource ('value previously saved via remember' or 'all saved keys'). It distinguishes the tool from siblings like remember and forget.

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

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

The description states when to use ('look up context stored earlier') and contrasts with re-deriving from scratch. It also mentions pairing with remember and forget, but does not explicitly state when not to use.

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

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

Annotations already provide readOnlyHint, idempotentHint, etc. The description adds behavioral details: mark_read affects future calls, poll-friendly, and specifics on returned fields. No contradiction, adds value beyond annotations.

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

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

The description is two sentences, front-loaded with key purpose and parameters. First sentence is somewhat long but every part earns its place. Minor room for brevity, 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?

No output schema, but description covers return fields (source, citation_uri, payload). Parameters are well documented. Combined with annotation coverage, tool is sufficiently described 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%, baseline 3. The description enhances parameter meaning, e.g., mark_read is explained as 'flag returned events read so the next call only shows newer ones', and since and type filters are clarified. Adds semantic 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 starts with a specific verb ('Pull') and clearly states the resource ('fired events from your subscription feed'). It distinguishes from sibling tools like list_subscriptions by focusing on recent alerts with specific fields, purpose is unambiguous.

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

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

The description explains when to use this tool and compares with an alternative ('the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards'), but doesn't explicitly state when not to use it. Still provides clear context for usage.

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

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

Annotations already indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds significant value by detailing the multi-source fan-out (SEC EDGAR, GDELT/GNews, USPTO), rate-limiting fallback, USPTO soft-fail, and the structured return format (changes[] grouped by source, total_changes count, citation URIs). No contradiction with annotations.

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

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

The description is moderately long but efficiently structured. It starts with example queries, then explains the tool's behavior, parameter notes, return structure, and sibling differentiation. Every sentence adds value; minor redundancy could be trimmed but overall well-organized for an AI agent.

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

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

For a tool with three required parameters and no output schema, the description covers all essential aspects: purpose, parameter semantics, behavioral nuances, return format, and alternatives. It is fully self-contained and enables correct invocation without external context.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds practical guidance: 'since' accepts ISO dates or relative shorthand with recommended defaults ('30d' or '1m'), 'value' can be ticker or zero-padded CIK with examples, and 'type' is limited to 'company'. This enhances clarity beyond the schema.

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

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

The description opens with concrete user queries ('What's new with X', 'latest on Y') that directly map to the tool's function: providing a change feed for a company over a recent window. It also explicitly distinguishes from the sibling tool 'entity_profile', which serves a different purpose (static profile).

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

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

The description provides explicit usage context: it tells when to use this tool (for dynamic changes) and when not to ('Use entity_profile instead when you want the static profile'). It also explains fallback behavior (GDELT preferred, GNews when rate-limited), guiding the AI on expected behavior.

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 details about scoping by identifier and persistence duration (24h for anonymous). Annotations already indicate idempotent and not destructive; description adds useful behavioral context 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?

Concise, front-loads purpose, no wasted words.

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

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

Given simple key-value nature and annotations, description covers usage, scope, lifetime, and related tools 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 already describes both parameters well (100% coverage). Description does not add additional parameter-level detail, but schema is sufficient.

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

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

Clearly states the tool saves data for later reuse. Mentions key-value pair and scoping. Distinguishes from recall and forget siblings.

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

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

Explicitly says when to use: when discovering something worth carrying forward. Provides context on scope and session duration. 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 (readOnly, idempotent, openWorld), the description adds that the tool cascades through several lookup endpoints internally and auto-disambiguates. It details return fields per type (ticker, CIK, RxCUI, etc.) and notes citation URIs, giving rich behavioral insight.

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

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

The description is relatively long but well-structured: it starts with user intent examples, states the primary use case, then details each supported type. Every sentence adds distinct value, though a slight tightening could improve conciseness without losing information.

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

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

Given no output schema, the description fully covers what the tool returns per entity type, including citation URIs. It explains input flexibility and internal cascading, addressing potential agent questions about behavior and response structure. Very complete for a lookup tool.

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

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

Schema coverage is 100% and descriptions are present, so baseline is 3. The description adds value by providing concrete examples of accepted formats (e.g., 'ticker (AAPL)', 'brand or generic name ("ozempic")') and explaining auto-disambiguation, which enhances understanding 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 resolves user-spoken names to canonical/official identifiers. It provides explicit examples ('What's the ticker for…') and specifies supported types (company, drug) with what each returns. It distinguishes itself by saying 'replaces 2-3 manual lookups' and is well-scoped for its role among siblings.

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

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

Explicitly states 'Use FIRST whenever you have a name but need an ID.' This directly guides when to use the tool. It also implies when not to use it (when IDs are already known) and provides context that it replaces multiple manual lookups, helping the agent 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?

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), description adds that each entity is probed with ai_visibility_check, returns ranked list with score, confidence, signal density. No contradiction.

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

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

Three sentences, no filler. Purpose, usage, and output state upfront. Every sentence earns its place.

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

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

Despite no output schema, description explains return type (ranked list with score, confidence, signal density). Covers purpose, parameters, behavior, and output shape comprehensively.

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

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

Schema has 100% description coverage. Description adds value: first entity treated as subject, models default to workers-ai, context disambiguates names. Provides meaning beyond schema.

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

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

Description clearly states it compares AI visibility across multiple entities, probes with ai_visibility_check, ranks by score, and surfaces most/least recognized. This distinguishes it from single-entity tool ai_visibility_check and generic compare_entities.

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

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

Provides explicit use case: competitive AI-marketing audits with example question. Implicitly suggests using when comparing brand recognition across competitors, but could explicitly state when not to use or name sibling 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?

Beyond annotations (readOnly, idempotent, etc.), the description discloses important behaviors: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and a 'sources_failed' list is provided on timeout. This adds significant value.

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

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

The description is well-structured, starting with the core purpose, then use cases, limitations, and behavioral notes. While it is verbose, every sentence adds value and it remains front-loaded with the most important 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?

Despite lacking an output schema, the description comprehensively lists return fields (summary block, advisories, links, versions) and explains handling of partial failures. For a complex tool with multiple external sources, 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?

The input schema already covers both parameters with descriptions. The tool description enriches this by explaining that 'version' defaults to latest when omitted and that scoped packages are accepted. The 'package' parameter's role in the composite check is contextually clarified.

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

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

The description clearly identifies the tool as a composite check for npm packages, combining deps.dev and bundlephobia. It specifies the exact use case: deciding whether to add an npm package, and distinguishes from sibling tools by focusing on npm ecosystem and package evaluation metrics.

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 directives are given: use when agent asks about safety/popularity/size or cost of adding an npm package. It also notes limitations (NPM only in v1; other ecosystems fall under deps.dev:version directly) and provides alternative for non-NPM packages.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, covering safety and idempotency. Description adds scope (Swiss public transport) but no additional behavioral insights.

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?

One sentence, no wasted words, perfectly concise for the complexity level.

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

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

Given the simple nature of the tool (1 param, output schema exists, annotations rich), the description is fully sufficient and leaves no gaps.

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

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

Single parameter with 100% schema coverage; description adds no new parameter details but reinforces the Swiss public transport 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?

Description clearly states search for Swiss public transport stations by name query, distinguishing it from related sibling tools like get_connections or get_stationboard.

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?

No explicit when to use or alternatives mentioned, but the purpose is clear enough that it is the go-to tool for station search; implicit usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and no destructive action. The description adds rich behavioral details: uses BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flag, and return of offsets/scores. No contradiction with annotations.

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

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

The description is a single, well-structured paragraph of about 5 sentences. It front-loads the main action, then provides examples, usage guidance, and technical details. 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 fully covers what the tool does, its parameters, behavior (embeddings, windows, cap), output (passages with offsets/scores), and how it complements sibling tools. No output schema exists, but description sufficiently explains return values.

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

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

Schema coverage is 100% with descriptions for all 3 parameters. The description reinforces these (e.g., max 200K chars for text, examples for query) and adds context on limit default (5) and char cap. It adds value beyond the schema but is not essential.

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 states 'Semantic search INSIDE a fetched record' with clear verb+resource. It provides specific examples (SEC 10-K, article, tool result) and distinguishes from fetching the whole document, making its purpose unambiguous among 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 says 'Use when the record is too big to cram into the prompt' and explains how it saves context. It mentions pairing with ask_pipeworx_grounded. However, it does not explicitly state when not to use it, which is a minor gap.

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 substantial context: auth needs, delivery constraints, and type-specific filters. However, the idempotentHint annotation is not reinforced—whether duplicate subscriptions return the same ID is unstated.

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 front-loaded purpose, but somewhat repetitive on delivery details that already appear in the schema.

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?

Thorough for a subscription tool, covering all types and delivery channels. Lacks explicit output schema (return format) and idempotency behavior, but overall 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?

The description enriches every parameter with concrete examples, format constraints, and business logic well beyond the schema's basic descriptions.

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

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

The description clearly states it creates a subscription to a live-data event stream, explicitly distinguishing it from sibling tools like list_subscriptions and unsubscribe.

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

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

Provides explicit account requirements and detailed type-specific parameters, but lacks explicit exclusions or 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 cover readOnly, idempotent, and non-destructive. The description adds detail on return format (category-bucketed examples with tool+argument shape) and data sources. 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 somewhat long but well-structured with a clear lead, bulleted list, and actionable instructions. Every sentence adds value, but slight trimming possible.

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

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

Given the complexity and lack of output schema, the description fully explains return content, usage scenarios, and when to use as entry point. Complete for an onboarding tool.

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

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

Schema covers 100% of the single parameter with description. The description adds context about omitting for full spread and lists focus areas, providing extra 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 this tool is the onboarding entry point that returns category-bucketed example questions. It uses specific verbs ('returns', 'call', 'use') and distinguishes from siblings by positioning itself as the first tool for new users.

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 FIRST'), how to call (no arguments or with topic), and mentions alternatives (meta-tools like ask_pipeworx). Provides clear context and exclusions.

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

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

Adds context beyond annotations: explains row is deactivated not deleted, linking to recent_alerts. Consistent with idempotentHint and destructiveHint.

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 sentence states purpose and constraint, second explains behavioral nuance. 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?

For a simple single-parameter tool with no output schema, the description covers purpose, usage constraint, and behavioral effect completely. Well-suited to the context.

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

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

Schema coverage is 100% and description reiterates the parameter's description from schema. No additional meaning provided 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?

Clearly states verb 'cancel' and resource 'subscription'. Distinguishes from siblings like subscribe and list_subscriptions by mentioning ownership and cancellation.

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 ownership enforcement and the behavioral consequence (deactivation vs deletion). Implies when to use, but does not explicitly mention when not to or 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?

Description adds substantial behavioral context beyond annotations: returns five verdict types, structured form, actual value with citation, and percent delta. It also states version and replacement of multiple calls. No contradictions with annotations (readOnlyHint consistent with verification).

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

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

The description is slightly long but well-structured. Front-loaded with user intent phrases and examples. Every sentence adds value, though some details (e.g., replacement of calls) could be integrated more concisely.

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

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

Given single required parameter and no output schema, the description covers input format, behavioral scope, and output details (verdict types, citation). It provides sufficient context for an agent to use correctly, though a brief mention of expected output schema would further completeness.

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 well-described 'claim' parameter. Description adds natural-language pattern examples, but beyond that, it does not add significant new semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: verifying natural-language factual claims against authoritative sources, with specific examples and scope (company-financial claims). It distinguishes itself from siblings by describing its unique capability and efficiency.

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 ('check whether something a user said is factually correct') and explains it replaces multiple sequential calls. It does not explicitly state when not to use, but the scope (financial claims) implies boundary.

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