Data Orlando

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds further transparency: default model is free, Anthropic requires a BYO API key (user pays), and the return structure includes per-model fields and a combined view. 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 three sentences, each serving a distinct purpose: function and output, default and optional API key, and use cases. No superfluous words, front-loaded with the core action.

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

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

Despite no output schema, the description adequately describes the return value structure. It covers all parameters and their roles. It does not mention error handling or edge cases, but for a straightforward probe tool, this is sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by clarifying the default model (workers-ai), the purpose of _apiKey (only needed for anthropic), and gives examples for entity and context 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?

The description clearly states the tool probes LLMs for knowledge about an entity and returns a visibility score. It uses specific verbs (probe, score) and specifies the resource (LLMs' knowledge) and output format (per-model results + combined view). Among sibling tools, there is no direct equivalent, so it is distinctive.

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

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

The description gives explicit use cases: 'AI-marketing audits, pre-launch brand checks, competitive monitoring.' It does not explicitly contrast with alternative tools like entity_profile or scan_competitor_ai_presence, but the provided context is sufficient for most use cases.

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

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

Annotations already indicate readOnlyHint, idempotentHint, etc. The description adds vital context: it routes to many sources, fills arguments, returns structured answers with stable 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?

While front-loaded with key guidance, the description is verbose, repeating 'ask_pipeworx' name and listing many examples. Could be more concise without losing value.

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

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

Given the tool's complexity (routing to 4,552 tools), the description is remarkably complete: it explains behavior, usage context, alternatives, and return format. No output schema, but description covers expectations.

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

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

Schema coverage is 100%; description adds no new param meaning beyond aliases. The description's param text is redundant with 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?

Description clearly states the tool routes questions to 4,552 tools and returns structured answers with citations. It distinguishes from siblings like ask_pipeworx_grounded and deep_research by specifying when to use each. The purpose is precise and actionable.

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

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

Explicitly recommends using this tool over web search for factual questions, provides examples of when to use ('what is', 'look up', etc.), and clearly states when to step up to alternatives (ask_pipeworx_grounded for hallucination-resistant answers, deep_research for broad questions). No ambiguity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as true/false, covering safety and mutability. The description adds valuable behavioral context: it explains the exact refusal reasons, the return structure, the additional LLM call cost, and the fact that it only uses the tool result. No contradictions are present, but the description could further detail the tool selection process.

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

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

The description is informative and front-loaded with the key benefit ('Hallucination-resistant answer mode'). It is slightly lengthy but every sentence adds value, covering behavior, return format, refusal reasons, and usage guidance. A minor trim could improve conciseness.

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

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

Given the absence of an output schema, the description thoroughly explains the return format (success and refusal structures), refusal reasons, and use cases. It also mentions cost and alternative tool, making it self-contained for an agent to understand the tool's capabilities and limitations.

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

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

Schema coverage is 100% with each parameter having a description. The description does not add new semantic meaning to the parameters themselves, but it explains how the tool uses the question to route and extract. Baseline 3 is appropriate as the schema already documents the aliases.

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

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

The description clearly defines the tool as a hallucination-resistant answer mode for high-stakes reads, contrasting it with its sibling tool ask_pipeworx by emphasizing grounded extraction and explicit refusal reasons. The verb 'EXTRACTS' and resource 'answer using ONLY what the tool result contains' precisely specify its function.

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

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

The description provides explicit guidance on when to use this tool ('whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts') and when to prefer the alternative ('prefer ask_pipeworx for casual lookups'), including a cost trade-off ('Costs one extra LLM call').

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

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

The description extensively discloses behavioral details beyond the annotations, including market resolution, classification, fan-out, safety mechanisms (low-confidence short-circuit, closed market handling), wide-spread liquidity flags, and resolution-rule risk. It also explains response shapes and fallback behavior for news sources. All of this adds significant transparency, exceeding the minimal burden since annotations already declare idempotency and safety.

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

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

The description is verbose and contains many sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), which is well-structured but not concise. While each sentence adds value, the overall length could be reduced without losing essential information. The front-loading is good (first sentence states purpose), but conciseness suffers.

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 comprehensively covers all aspects: input formats, classification, fan-out examples, response structure, resolver contract, parent event extraction, news fallback behavior, safety, liquidity, and resolution-rule risk. No gaps are apparent; an agent has all information needed to understand the tool's behavior and results.

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

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

Schema coverage is 100% and the schema descriptions for market, depth, and include_raw are clear. The description does not add new semantic information about the parameters beyond what is already in the schema. It mentions how to pass the market input and provides examples, but the schema already covers this. Hence, baseline score of 3.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the resource (Polymarket bet) and action (research via Pipeworx data), with examples of when to use it. However, it does not explicitly distinguish itself from sibling tools like polymarket_edges or polymarket_arbitrage, so it falls short of a perfect 5.

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

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

The description provides three use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This gives clear context for when to use, but it lacks guidance on when not to use and does not mention alternatives. The 'when-not' and alternative tools are not addressed, resulting in a score of 3.

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. Description adds details on data sources, handling of off-calendar fiscal years, sorted results, and citation URIs, exceeding annotation coverage.

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

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

Single paragraph is concise and front-loaded with example queries. Every sentence adds value, though slightly dense; could be slightly more structured but overall efficient.

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

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

Covers purpose, usage, data sources, sorting, and efficiency gains. Lacks exact output structure but is sufficient given no output schema and low parameter count.

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

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

Schema coverage is 100%, but description adds meaningful examples (tickers/CIKs for company, drug names), explains enum differences, and specifies min/max items, adding 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 uses specific verbs like 'compare' and clearly states it performs side-by-side comparisons of 2–5 companies or drugs. It gives example queries and distinguishes from sequential 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 advises to prefer over sequential single-pack lookups when comparing entities. Provides context on when to use (comparisons) but does not explicitly list exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds behavioral context beyond annotations: it explains the search mechanism, the structure of results (fields), and the intended follow-up action, enriching what the agent knows about the tool's behavior.

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

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

Two sentences with no superfluous words. The first sentence states the core function, the second adds the return fields and a crucial next-step instruction. 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 lacking an output schema, the description fully covers the return information by listing the fields and explaining how to use the results with another tool. Given the annotations provide safety context, this is complete for a search tool.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters. The description adds minimal extra meaning for the 'query' parameter by specifying it searches titles/descriptions, but does not enhance 'limit' or 'offset' beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'search', the resource 'Orlando Open Data catalog of open datasets', and the mechanism 'by keyword'. It also lists the specific return fields, making the purpose highly specific and distinguishable from sibling tools, which are unrelated domains.

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?

While not explicitly stating when not to use, the description implies a workflow by mentioning 'pass the resource_id to query/metadata', guiding the agent on follow-up tool usage. This provides clear context, but lacks explicit exclusions 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?

Beyond annotations (readOnly, idempotent, openWorld), description reveals time expectation (15-60s), output format (findings packet with evidence, gaps, citations), data source type, and account tier restriction for 'thorough' depth. Adds substantial behavioral context.

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

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

Description is lengthy but well-structured with critical info front-loaded (account requirement, fallback). Each sentence serves a purpose, though slight redundancy in explaining decomposition. No wasted words, but could be more compact.

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 tool complexity (multi-source parallel research), description covers purpose, behavior, limitations, prerequisites, examples, time, and output format. No output schema, but return packet is described well. Fully prepares agent for correct invocation.

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

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

Schema covers 100% of parameters, but description adds meaning: explains depth enum values (quick=3, standard=5, thorough=8 paid) and clarifies question should be broad/natural language. Minor addition to already well-documented 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 grounded multi-source research across 1160 structured databases, decomposes questions, and routes to tools in parallel. It distinguishes itself from siblings like ask_pipeworx by contrasting scope and data source type.

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 (broad/multi-part structured data), when not (single lookup or breaking news), and provides alternative tools (ask_pipeworx). Also specifies account requirements and fallback for unsigned users.

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. Description adds that results are ready to call directly without second schema lookup, providing useful beyond-annotation context.

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

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

Front-loaded with main purpose, then lists domains, then details. Slightly lengthy due to domain list, but each element serves a purpose. No wasted sentences.

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

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

With no output schema, description adequately describes return structure: names, descriptions, and full input schemas with curated examples. Covers what agent needs to know.

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

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

Schema coverage is 100% with descriptions for all parameters. Description mentions aliases for query parameter, adding minor value, but baseline is 3 for complete 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 finds tools by describing data or task, lists numerous domains, and specifies it returns top-N relevant tools with schemas. This distinguishes it from siblings that provide direct answers.

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', indicating when to use. Could be improved by stating when not to use or suggesting alternatives.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds further behavioral details like USPTO API sunset (soft-fail) and return structure, but does not mention rate limits or authentication beyond what annotations imply.

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

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

Description is informative and front-loaded with example queries, but it is longer than necessary. However, every sentence contributes value, and the structure is logical.

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

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

Despite no output schema, the description lists all returned fields (cik, company_name, filings with URIs, fundamentals, patents, news, LEI), which is sufficiently detailed for a complex tool. Covers fallback behavior and limitations.

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

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

Schema has 100% coverage with descriptions. The description reinforces that value can be a ticker or zero-padded CIK and explicitly states names are not supported, adding 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 clearly states it produces a 'full cross-source profile of a US public company' and lists specific content areas (SEC, XBRL, news, etc.). It distinguishes itself from alternative approaches like chaining single-pack lookups.

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

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

Explicitly says 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and notes that names are not supported, directing users to resolve_entity instead.

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 destructiveHint=true. Description adds context about use cases but no additional behavioral traits beyond the destructive nature.

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, front-loaded with purpose, no wasted words.

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

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

With 1 required param, annotations, and no output schema, description fully covers what the tool does and when to use it.

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

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

Schema coverage is 100% and description doesn't add meaning beyond what the schema already provides for the single parameter 'key'.

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

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

Description uses a specific verb 'Delete' and resource 'memory by key'. It clearly distinguishes from siblings 'remember' and 'recall'.

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

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

Explicitly states when to use: stale context, task done, or clearing sensitive data. Also mentions pairing with related tools.

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

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

Annotations indicate read-only, open-world, idempotent, non-destructive. Description adds that it fetches the page, extracts title/description/key links, and emits standard markdown. No contradictions, but could mention potential failures (e.g., unreachable URL).

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: first gives core purpose, second describes process, third lists use cases. No fluff, front-loaded, each sentence adds value.

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

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

With no output schema, the description explains the output (single text blob). Parameters are few and well-documented in schema. Agent has enough context to use the tool correctly.

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

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

Schema coverage is 100%, so description's role is reduced. However, the description adds the default value for max_links (25) beyond the schema's max 50, aiding agent understanding. The description also clarifies that the output is a text blob.

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 the output format and target AI crawlers. It distinguishes itself from sibling tools like scan_competitor_ai_presence by focusing on generating the file rather than scanning presence.

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

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

Explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing competitors. Does not explicitly state when not to use it, but the context suggests it's specifically for this llms.txt generation task.

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 false. Description adds that it returns specific fields and that it shows 'active' subscriptions by default, complementing annotations well.

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

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

Two sentences, front-loaded with action and return info. Every sentence adds value, no waste.

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

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

For a simple read-only tool with one optional param and no output schema, the description is complete. It covers purpose, return fields, and usage scenario.

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

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

Schema coverage is 100%, so baseline is 3. Description does not add extra meaning beyond schema; it only mentions 'active subscriptions' which aligns with the default false for include_inactive.

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

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

Clearly states it lists the caller's active subscriptions and specifies returned fields (id, type, params, etc.). Distinct from siblings like subscribe and unsubscribe, which perform different actions.

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 reviewing monitoring before adding more or finding an id to cancel. Provides clear context but could mention the include_inactive parameter for viewing cancelled ones.

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

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

Annotations already declare readOnly and idempotent. Description adds value by specifying return fields (columns, types, row count, category, last-updated), enhancing transparency without contradictions.

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

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

Single, well-structured sentence front-loads the action and resource, with no extraneous information. Every word contributes to 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?

Fully complete for a simple read-only tool with one parameter. Description covers the return values adequately, and annotations provide safety and idempotency guarantees. No output schema 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 coverage is 100% with a clear description for resource_id. Description adds an example but no new semantic meaning beyond the schema, so baseline 3 is appropriate.

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

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

Description clearly states the tool retrieves schema and metadata for a dataset, listing specific fields and providing an example resource_id, making the purpose unambiguous and distinct from siblings like 'datasets'.

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?

Implies usage when you have a resource_id, but no explicit guidance on when to use vs alternatives or prerequisites. Missing context like where to obtain the resource_id.

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

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

Description discloses rate limit (5 per identifier per day), free usage, and no quota impact. Annotations are all false and not contradicted; description adds significant behavioral context.

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

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

Five sentences, each essential, front-loaded with purpose. No redundant information; efficient and clear.

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

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

For a simple feedback tool with no output schema, the description comprehensively covers usage scenarios, restrictions, and format guidelines. Complete for its complexity.

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

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

Schema coverage is 100% with detailed enum and descriptions. Description adds extra guidance on how to phrase feedback (in terms of Pipeworx tools/packs) and length constraints, providing value beyond schema.

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

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

The description clearly states the verb 'tell' and resource 'Pipeworx team', and specifies the feedback types (bug, feature, data_gap, praise). It is distinct from all sibling tools, which are query, research, subscription, etc.

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

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

The description explicitly lists when to use (bug, feature, data_gap, praise) and what not to do (don't paste the end-user's prompt). No alternatives are needed as there are no sibling feedback tools.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds valuable context: it is self-aggregating, derived from CF analytics engine, no PII, and cached 5min-1h. This goes beyond annotations, though it could mention potential rate limits or auth requirements.

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

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

The description is four concise sentences. The first sentence clearly states the main output, and the following sentences front-load the use cases. Every sentence adds value with no wasted words.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete: it explains the output structure (top tools, top packs, total call volume), caching, and data source. It could optionally mention if the output is sorted or aggregated, but it is sufficient for an agent to understand the tool's behavior.

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

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

The schema already covers the parameter 'window' with enum and description (100% coverage). The description adds meaning by explaining that shorter windows surface hot trends while longer windows show steady-state demand, providing additional decision support 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 explicitly states the tool returns top tools, top packs, and total call volume over a recent window. It clearly distinguishes from sibling tools like 'ask_pipeworx' or 'discover_tools' by focusing on trending usage rather than individual queries or discovery.

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

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

The description provides three concrete use cases (discovering hot data sources, confirming canonical tool, aligning use case). It also mentions caching behavior. However, it does not explicitly state when not to use the tool or provide alternatives, which would elevate it to a 5.

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. The description adds substantial behavioral context: how the tool walks child markets, computes partition checks, applies semantic anchor (Jaccard similarity), filters partitions with placeholders, and performs a fill check against live CLOB depth. It also notes that some queries may return null signals. 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 comprehensive but slightly verbose with multiple paragraphs. It front-loads the main purpose and uses bold for key terms, which aids readability. Given the complexity of the tool, the length is justified, but some details could be streamlined or moved to separate documentation.

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

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

The description covers the response structure (opportunities[], partition_check, fill_check) and explains when results are actionable. With annotations present and 100% schema coverage, it provides sufficient context for an AI agent to understand the tool's behavior and limitations. However, a fully detailed output schema would improve completeness further.

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

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

Schema coverage is 100% with descriptions for both 'event' and 'topic'. The description enriches these by explaining the behavior of each mode: for 'event', it walks child markets, checks ordering, and computes partition_check; for 'topic', it searches related events, flattens markets, and runs the comparator on the union. This adds meaningful context beyond the schema.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies three distinct modes (no args, event, topic) and differentiates from sibling tools by focusing on arbitrage detection rather than edge tracking or fill risk.

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

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

The description provides explicit guidance on when to use each mode: no args for trending scan, event for specific markets (recommended), topic for cross-event scanning. It includes examples of valid inputs (e.g., 'fed-decision-may-2026') and explains when not to trade (if fill check shows realizable edge ≤ 0). It also points to an alternative tool for custom sizing.

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

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

Annotations already indicate readOnly, idempotent, openWorld, and non-destructive behavior. Description goes far beyond by detailing the three model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), response structure (by_segment, fed_candidates, _diagnostics), calculation details (edge_pp_net, kelly_fraction, slippage), and caching behavior (1h KV cache). 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 lengthy but well-structured with logical sections (model segments, knobs, response structure). Every sentence provides essential information given the tool's complexity. Could be slightly more concise, but front-loaded with the core purpose and usage context.

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

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

Given no output schema, the description thoroughly explains the response fields (by_segment, fed_candidates, _diagnostics) and edge case handling (why segments may be empty, filter_skips). It covers model details, Kelly calculation, slippage assumptions, and tradeable-edge criteria. The tool is highly complex, and the description accounts for all aspects an agent needs to use it effectively.

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

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

Schema coverage is 100% with good parameter descriptions, but the tool description adds substantial value: it explains how parameters like min_kelly, min_partition_leg_kelly, and tradeable-edge filters interact with the models. It clarifies that min_kelly does not filter partition arbs and that min_partition_leg_kelly applies to per-leg Kelly inside top_legs. This contextual information greatly enhances parameter semantics.

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

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

Description explicitly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It also expresses the use case 'what should I bet on today' and distinguishes from paging hundreds of markets. Clear differentiation from siblings like polymarket_arbitrage and polymarket_edge_tracker is implied but not explicit; however, the purpose is very specific and well-defined.

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

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

Tool provides clear context for when to use it (discovering betting opportunities without manual scanning) and includes configurable knobs (min_liquidity, max_spread_pp) that help agents filter out non-tradeable opportunities. It does not explicitly state when to use alternatives like polymarket_arbitrage or edge_tracker, but the context makes it evident this is the primary edge discovery tool.

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

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

Annotations indicate safe, read-only behavior. The description adds details on response structure (tracked[], expired[], snapshot_dates[]), limitations (60-day TTL), and interpretation (decay from daily closes), going well beyond the annotations.

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

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

The description is lengthy but well-organized with clear sections (core question, RESPONSE details, LIMITS). Every sentence adds value, though it could be more concise.

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

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

With no output schema, the description fully explains return fields and their meanings, including edge_pp_net time-series, trend categorization, and snapshot coverage, ensuring the agent understands the output 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?

Input schema covers both parameters with clear descriptions. The tool description adds minor clarifications (e.g., 'max 30' vs 'clamp 2-30') but does not significantly enhance 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 provides 'edge persistence and decay telemetry' from daily snapshots, answering 'how long has this edge existed and is it shrinking?'. It distinguishes itself from sibling 'polymarket_edges' by focusing on historical trends rather than current edges.

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

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

The description implies when to use—comparing fresh vs old edges—and provides context on interpreting results, but does not explicitly contrast with alternative tools or state when not to use it.

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

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

Annotations (readOnlyHint, idempotentHint) are consistent with description. The description details behavior: walks order book ladder, returns fill details, slippage, verdict, and for basket mode warns about forced directional risk. No contradictions.

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

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

Description is long but well-structured. It front-loads the core purpose, then explains modes, parameters, and usage sequentially. All sentences are informative, though slightly verbose.

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

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

Given the complexity (two modes, many return fields, no output schema), the description is very complete. It details all return fields for both modes and warns about risks. Output schema is absent, but description compensates fully.

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

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

Schema coverage is 100%, so baseline 3. Description adds meaning: explains 'side' auto default for basket, 'size_usd' as settlement notional for basket, shares per leg, and default/bounds. This adds value beyond schema.

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

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

The description clearly states the tool's purpose: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes between single-market and basket modes, and explicitly contrasts with siblings like polymarket_arbitrage and polymarket_edges. The verb 'check' and resource 'fill risk' are specific.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also warns against partial fills converting arb into unhedged positions, providing clear context.

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

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

Annotations already confirm readOnly, idempotent, non-destructive behavior. The description adds significant behavioral context: compatibility_warning trigger conditions, temporal alignment checks, skipped cross-type/subtype counters, and the structure of the response. 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 well-structured with clear sections but is slightly verbose, repeating some points (e.g., compatibility_warning mentioned twice). It is front-loaded with the core purpose and modes, but could be trimmed by 15-20% 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 no output schema, the description fully explains the response format (leg-by-leg prices, matched spreads, safety fields). It covers edge cases like temporal misalignment and shape mismatches. The complexity of modes and warnings is handled thoroughly.

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?

All three parameters are fully described in the schema (100% coverage). The description adds value by explaining the topic mode's pre-mapped shortcuts, the override behavior for explicit tickers, and examples. It also clarifies that neither parameter is required, with topic as a default mode.

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

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

The description clearly states the tool computes the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by specifying cross-venue focus and explaining the logic of comparability.

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 two explicit modes (topic shortcuts and custom event IDs) and explains when each is appropriate. It warns that most pre-mapped topics currently return compatibility warnings, guiding users away from false expectations. However, it does not explicitly contrast with alternative tools like polymarket_arbitrage for single-venue analysis.

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, so the safety profile is clear. The description adds that it returns matching rows as JSON, which is useful but not a behavioral trait beyond what annotations already indicate.

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

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

The description is a single, efficient sentence that immediately conveys the tool's purpose, target data source, and key parameters. No unnecessary words.

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

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

The description covers the essential query capabilities and return format. Given 7 parameters and no output schema, it might benefit from noting result limitations (e.g., default limit) or pagination behavior, but these are implied by the parameters.

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 the schema already documents each parameter adequately. The description reinforces usage (e.g., 'without the leading $') but does not add new semantic 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 runs a Socrata SoQL query against a specific dataset using a resource_id, and lists the filtering clauses. It effectively distinguishes this tool from siblings like 'datasets' or 'search_within' by specifying the query syntax.

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

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

The description explains the tool's purpose and parameters (where, select, group, order, limit, offset), providing clear context for when to use it. However, it does not explicitly mention when not to use it or suggest alternatives, which would improve guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, aligning with the description. The description adds useful behavioral context about scoping to identifiers and pairing with 'remember' and 'forget', which is beyond what annotations provide.

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

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

The description is concise (~4 sentences) with the core action in the first sentence. 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?

With only one optional parameter, no output schema, and comprehensive annotations, the description covers all necessary context: purpose, usage variation (list vs. retrieve), scope, and integration with siblings.

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

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

Schema coverage is 100%, and the schema already explains the parameter ('omit to list all keys'). The description adds minimal extra meaning (e.g., 'previously saved via remember'), so baseline 3 is appropriate.

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

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

The description clearly states the verb 'retrieve' and the resource 'value previously saved via remember' or 'list all saved keys'. It distinguishes itself from siblings by naming '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 explains when to use ('look up context the agent stored earlier... without re-deriving it from scratch') and mentions scoping. It does not explicitly state when not to use, but the context implies it's for retrieval only.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that setting mark_read:true flags events as read, affecting future calls — a behavioral trait beyond what annotations provide. 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 compact (5 sentences) with no redundancy. Each sentence adds value: purpose, returned fields, filtering, mark_read behavior, polling, and alternative endpoint. Front-loaded with the main action.

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

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

Given no output schema, the description adequately summarizes what is returned (source, citation_uri, raw payload). It could mention ordering (presumably by recency) but otherwise covers the tool's core behavior and parameters.

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 context: mark_read's effect on future calls, and the meaning of filter parameters (type, since). This enhances understanding beyond the schema's own descriptions.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifies returned fields (source, citation_uri, raw payload), and filters by type/since. The verb 'Pull' combined with 'fired events from your subscription feed' distinguishes it from siblings like list_subscriptions or recent_changes.

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 notes that polling works fine and points to an alternative GET endpoint for scripts/dashboards, implying this is for programmatic use. However, it does not explicitly compare to siblings like list_subscriptions or recent_changes, leaving some ambiguity about when to use this versus 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 (readOnlyHint, etc.), the description details multi-source fan-out (SEC, GDELT→GNews fallback, USPTO), date acceptance formats, and return structure (grouped changes, total count, citation URIs), adding significant behavioral context.

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

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

The description is concise yet comprehensive, front-loaded with purpose and examples, followed by source details, parameter explanation, and alternative tool guidance—every sentence earns its place without redundancy.

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

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

Despite no output schema, the description fully explains return format (changes grouped by source, total_changes count, citation URIs) and covers all critical aspects: sources, fallbacks, parameter formats, and usage context, making it self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'since' accepts ISO date or relative shorthand with examples ('7d', '30d', '3m', '1y') and clarifies 'value' can be ticker or CIK, exceeding the schema descriptions.

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

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

The description explicitly states the tool provides a 'change feed for a company in the last N days/weeks/months' with example queries like 'What's new with X', and distinguishes from sibling tool 'entity_profile' which serves a different purpose.

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

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

The description gives explicit when-to-use guidance, including a direct alternative: 'Use entity_profile instead when you want the static profile...', and provides example input patterns for various use cases.

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

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

Adds key context beyond annotations: scoped by identifier, authentication persistence vs anonymous 24-hour retention. Annotations (idempotentHint=true, destructiveHint=false) are consistent with description. No contradiction.

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

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

Four sentences with no wasted words. Front-loaded with purpose, then use case, then storage details, then tool pairing. Each sentence earns its place.

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

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

For a simple tool with no output schema, description covers all necessary aspects: purpose, when to use, storage mechanics (key-value, scoped, persistence), and relationships to sibling tools. Complete for effective 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%, so baseline 3. Description adds examples of keys ('subject_property', 'target_ticker') and clarifies value as 'any text', providing meaning beyond the schema's generic 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?

Description uses specific verb 'Save data' and explicit resource 'key-value pair' with concrete examples (resolved ticker, target address). Distinguishes from siblings like 'recall' and 'forget' by mentioning them.

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 you discover something worth carrying forward') and pairs with tools 'recall' and 'forget' for retrieval and deletion. No misleading guidance.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the tool cascades through several lookup endpoints internally and provides details on return values (e.g., CIK, RxCUI, citation URIs) beyond the schema. This adds useful behavioral context.

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

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

The description is relatively concise, starting with compelling examples and then stating the purpose. It packs significant detail about supported types and return formats. Minor improvement could be even tighter structuring, but it is effective and front-loaded.

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

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

Given the tool's moderate complexity (2 params, no output schema, full annotations), the description is complete. It explains input formats, return values for each type, and mentions auto-disambiguation and internal cascading. No gaps remain for effective usage.

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

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

Schema coverage is 100% (baseline 3). The description adds meaning by explaining the return formats for each type (e.g., company returns ticker + CIK + company_name + citation URI) and providing examples for the 'value' parameter, enriching the schema beyond basic descriptions.

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

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

The description clearly states the tool resolves user-spoken names to canonical identifiers, with explicit examples like 'What's the ticker for...' and support for company and drug types. It distinguishes from sibling tools like 'entity_profile' and 'compare_entities' by focusing on ID lookup.

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

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

The description gives explicit guidance: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces multiple manual lookups, providing strong context. However, it does not explicitly mention when not to use it or alternatives for unsupported entity types, which would elevate it to a 5.

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, and no destructiveness. The description goes beyond by explaining that each entity is probed with ai_visibility_check, results are ranked, and optional context is applied. It does not contradict annotations and adds meaningful behavioral context about internal delegation and output structure.

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

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

The description is front-loaded with the main action, uses 3-4 concise sentences, and contains no fluff or redundancy. Every sentence contributes to understanding the tool's purpose, usage, and output.

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

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

Given no output schema, the description compensates by stating the return includes a ranked list with score, confidence, and signal density per entity. Parameters are well-covered. Annotations handle safety. Minor gap: 'signal density' is not defined, and no mention of pagination or limits, but overall sufficient for an agent to use the tool correctly.

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

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

Schema coverage is 100%, but the description adds extra meaning beyond the schema: it specifies that the first entity is treated as the 'subject' for narrative, notes default model (workers-ai), and clarifies context usage. This additional guidance helps the agent understand parameter semantics beyond type and format.

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 compares AI visibility across multiple entities side-by-side, using ai_visibility_check, and returns a ranked list with scores. It distinguishes from sibling ai_visibility_check (single entity) by specifying multi-entity comparison and ranking, and provides a concrete use case for competitive AI-marketing audits.

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 the tool is useful for competitive AI-marketing audits and gives an example question, implying when to use it. However, it does not explicitly state when not to use it or mention alternative tools like ai_visibility_check for single entity comparisons, which would have made it a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. The description adds significant behavioral context: composite fan-out across two APIs, partial failures degrade gracefully, bundlephobia first measurement can take 5-30 seconds, and sources_failed will list timeouts. This fully informs the agent of system behavior beyond annotations.

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

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

Description is fairly long but well-structured with front-loaded purpose. Every sentence adds value: composite nature, fan-out details, use-case, ecosystem limit, and failure behavior. Minor verbosity but no wasted words.

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

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

Despite no output schema, the description thoroughly details the return structure: summary block fields (is_latest, license, published_at, advisory_count, bundle_kb_min, bundle_kb_gz, dependency_count, has_esm, tree_shakeable), per-advisory detail, links, recent alternatives, and sources_failed. This is complete for such a complex composite tool.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds minimal extra: confirming scoped packages (@types/node) are accepted and that version defaults to latest when omitted. This adds some context but does not significantly improve 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's a composite check for adding npm packages, combining deps.dev (license, advisories, version history) and bundlephobia (bundle size, dependency count, ESM/tree-shake). It distinguishes from siblings by specifying the exact scope (NPM ecosystem only in v1) and the alternatives for other ecosystems.

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 an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'. It also provides exclusion guidance (NPM only; for PyPI/Maven/Cargo/Go use deps.dev:version directly) and mentions partial failure 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?

Discloses embedding model (BGE-base-en), windowing (500-char overlapping windows), character cap (200K with truncation flagging), and that passages include offsets. Annotations already indicate read-only, idempotent, open-world; description adds these technical details 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?

Two front-loaded sentences plus a concise technical note. Every sentence contributes meaning: purpose, usage guidance, return format, embedding details, and constraints. No wasted words.

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

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

Despite no output schema, the description explicitly mentions return values (top-N passages with offsets and scores), and covers all behavioral details (truncation, model, windowing). Complete for a search tool.

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

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

Schema coverage is 100%, but description adds valuable context: notes the ~200K char limit for 'text', gives example queries for 'query', and specifies the range (1-20) for 'limit'. These go beyond the schema descriptions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with a specific verb+resource. It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded, and provides explicit context for when to use it.

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 the record is too big to cram into the prompt') and provides an alternative tool (ask_pipeworx_grounded) for grounding over passages.

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

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

Discloses auth requirements, delivery caps, and phone verification. Annotations include idempotentHint=true but description says 'Returns the new subscription id,' which could imply non-idempotent behavior; however, no direct contradiction. Description adds value beyond annotations by detailing constraints.

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

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

Front-loaded with main purpose, but lengthy due to comprehensive detail. Every sentence adds value, though some repetition between description and schema info. Could be slightly tighter but overall efficient.

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

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

Covers return value, auth, delivery options, limitations, and type-specific parameters. No output schema, so description adequately explains what the tool returns. Lacks error scenarios, but sufficient 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 coverage is 100%, and description enriches parameters with type-specific examples, required fields, and constraints (phone must be verified, 10/day cap). Adds meaningful context beyond schema definitions.

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

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

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

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

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

Explicitly requires a Pipeworx OAuth account, notes that anonymous and BYO cannot persist subscriptions. Lists supported types with parameter examples and delivery channel options including limitations (phone verification, 10/day cap). Lacks explicit 'when not to use' but context from siblings provides differentiation.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it returns category-bucketed example questions with exact tool+argument shapes, and is the onboarding entry point. No contradictions.

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

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

The description is front-loaded with alternative queries and structured with a clear list of categories. While slightly long (6 lines), it earns its place by providing comprehensive guidance without redundancy.

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

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

Given only one optional parameter, no output schema, and detailed annotations, the description fully covers the tool's purpose, when to use it, and what it returns. It is complete for an onboarding/discovery tool.

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

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

Schema coverage is 100% (1 parameter, 'topic'). The description adds meaning beyond the schema by listing possible topic values ('finance', 'pharma', etc.) and explaining the effect of omitting the parameter ('full spread'). This provides extra context for tool selection.

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 is the onboarding entry point that returns category-bucketed example questions. It specifies the verb ('suggest_questions' is implied via examples) and the resource (Pipeworx capabilities). It distinguishes from siblings by mentioning it teaches how to call meta-tools.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also provides usage options: call with no arguments for full spread or pass a topic to focus.

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 behavioral context beyond annotations: ownership enforcement and deactivation instead of deletion, which aligns with the destructiveHint=false annotation.

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 action, then key constraints. 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 the simple schema and annotations, the description fully covers what the tool does, its side effects, and constraints.

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

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

Schema has 100% coverage for the single 'id' parameter, so description adds minimal additional meaning beyond the schema.

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

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

The description clearly states the action 'Cancel a subscription by id' with a specific resource, and it distinguishes from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

Provides ownership restriction and explains that the row is deactivated, not deleted, which informs usage. Could explicitly mention checking subscriptions first, but the context is 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 declare readOnlyHint, openWorldHint, idempotentHint. Description adds behavioral context: returns verdict with citation, works via SEC EDGAR + XBRL, provides percent delta. 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, dense paragraph front-loads purpose with examples, then scope, then output. No wasted words.

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

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

With one parameter, full schema coverage, no output schema, the description sufficiently explains domain, input format, output details, and efficiency gains.

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% with description for 'claim'. Description reinforces with examples of valid claims and explains output format, adding 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?

Description clearly states the tool's purpose: verify factual claims, specifically company-financial claims via SEC EDGAR + XBRL. Uses example queries and distinguishes itself by noting it replaces multiple sequential calls.

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

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

Explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and scopes to company-financial claims. Lacks explicit 'when not to use' but provides sufficient context.

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