nationalize

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

The description adds operational details beyond annotations: default model (Workers AI), free vs paid (Anthropic BYO key), and return structure (per-model {score, confidence, signals, raw_response} + combined view). No contradiction with annotations (readOnlyHint, etc.) as it is a read-only probe.

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 (3 sentences), front-loaded with core purpose and output, then model details, then use cases. 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 tool's moderate complexity, 100% schema coverage, and no output schema, the description adequately covers purpose, parameters, usage context, and return structure. The combined view is mentioned but not detailed, which is acceptable.

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 meaning: explains default model for 'models', clarifies that '_apiKey' is only needed for Anthropic and is passed through, and describes return fields not in schema. Slightly above baseline 3 due to these enrichments.

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 ('probe', 'score') and resource ('LLMs', 'entity'), specifies the output format (visibility score 0-100 per model), and distinguishes from sibling tools like 'scan_competitor_ai_presence' by detailing the scoring mechanism and default model.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and implies when to use (brand visibility checks), but does not explicitly mention when NOT to use or compare to siblings like 'entity_profile' or 'scan_competitor_ai_presence'.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds valuable context: it routes to 3,745 tools, fills arguments, and returns structured answers with stable pipeworx:// citation URIs. 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 well-structured with a strong front-loaded preference statement and concrete examples. While somewhat lengthy, each sentence adds value for an agent deciding to use the tool.

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

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

Given the tool's complexity (3,745 tools, 884 sources) and no output schema, the description fully explains the routing behavior, citation format, and all structured data domains. It leaves no ambiguity about its capabilities.

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

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

Schema coverage is 100% with all parameters clearly described as aliases for 'question'. Description does not add new semantics beyond stating the parameter accepts natural language; examples in schema provide sufficient context.

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

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

Clearly states it handles factual questions about structured data (SEC filings, drugs, economics, etc.) and distinguishes itself from web search. The verb 'ask' and resource 'Pipeworx' are well-defined with concrete examples.

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

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

Explicitly instructs to prefer over web search for many domains and gives specific example questions. However, it does not explicitly state when not to use it (e.g., for conversational or unstructured queries).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral details beyond this: the extraction-only mechanism, explicit refusal reasons (not_in_source, no_tool_match, etc.), return format with evidence and confidence, and cost tradeoff ('costs one extra LLM call'). No contradiction with annotations.

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

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

The description is well-structured and front-loaded with key information. Every sentence adds value. It is slightly lengthy but appropriate given the complexity. Could be trimmed slightly, but no unnecessary repetition.

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 (hallucination-resistant, high-stakes), no output schema, 6 parameters, and 28 sibling tools, the description fully covers: what it does, when to use, return format (success and failure), refusal reasons, cost tradeoff, and relation to sibling. It is complete for agent decision and 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 description coverage is 100%, so the schema already documents all 6 parameters (question and its aliases). The description does not add new parameter-level semantics beyond stating that it 'fills arguments' generically. Per guidelines, baseline is 3 when coverage is high, and description adds no additional value for parameters.

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

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

The description clearly states the tool's purpose as a 'hallucination-resistant answer mode for high-stakes reads'. It specifies the verb ('extracts the answer using ONLY what the tool result contains') and resource (Pipeworx). It distinguishes from the sibling 'ask_pipeworx' by noting the extra LLM call and use cases.

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

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

Explicit guidance on when to use: 'when an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements)'. Also provides when not to use: 'prefer ask_pipeworx for casual lookups'. Directly names the alternative tool.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. Description adds that results include country codes with probability scores, which is helpful but does not disclose any surprising behavioral traits.

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 verb and resource, no wasted words. Efficient and clear.

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

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

Given the simple single-parameter input and annotations, the description fully explains input constraints and output format. No missing context.

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

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

Schema covers the 'names' parameter fully with description and maxItems. Description adds that it processes first names and returns results, but does not add significant meaning beyond the schema.

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

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

Clearly states the tool predicts nationalities for multiple first names (up to 10) and returns country codes with probabilities. The description distinguishes it from the sibling tool predict_nationality which is for single names.

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 to process name lists efficiently', implying batch usage. Does not explicitly mention when not to use or the alternative single-name tool, but context is clear.

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only operation. The description adds extensive behavioral context: fan-out logic, classifier list, response shapes (market, analysis, evidence), resolver contract with match confidence, parent event extraction, news fallback fields, safety handling for low-confidence matches, closed markets, wide spreads, and cancellation rule parsing. This goes well beyond annotations, providing comprehensive transparency.

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

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

The description is verbose and packed with detail, which is valuable but potentially overwhelming. It is well-structured with sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.), but the length could be reduced by linking to external docs. It earns a 3 as it is moderately concise for the amount of information.

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

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

Given the tool complexity (3 parameters, no output schema, but rich behavioral details), the description is complete. It covers input formats, fan-out behavior, response structure, error conditions (low confidence, closed markets, wide spreads), cancellation rules, and news fallbacks. No gaps are apparent for an AI agent to use the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema: it explains the market input can be slug, URL, or question text; depth defaults to 'thorough'; include_raw defaults to false with a recommendation. This enriches parameter understanding, earning a 4.

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

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

The description clearly states the tool researches a Polymarket bet by pulling Pipeworx data. It specifies input types and output structure. However, it does not explicitly distinguish this tool from siblings like polymarket_edges or polymarket_edge_tracker, which are also related to Polymarket betting. The verb 'research' and resource 'Polymarket bet' are specific, but sibling differentiation is lacking, earning a 4.

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

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

The description provides explicit usage examples: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"' and describes typical queries. It does not explicitly state when NOT to use the tool or mention alternatives among siblings, but the context is clear. This meets the 'clear context' level, earning a 4.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds specific behavioral details: data sources (SEC EDGAR/XBRL, FAERS), off-calendar fiscal year handling, sorted results, and citation URIs. Adds value beyond annotations without contradiction.

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

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

Description is a single paragraph of ~10 sentences, each adds value (query examples, behavioral rules, data specifics). No redundancy, but length could be slightly trimmed without losing content.

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

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

No output schema, but description states returns 'paired data + pipeworx:// citation URIs per entity'. Covers data sources, sorting, and efficiency. Missing details on exact response structure or error handling, but sufficient for an API 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 enriches semantics: explains that type='company' pulls 10-K data and type='drug' pulls FAERS data. Provides examples for values (tickers/CIKs, drug names), clarifying expected input beyond the schema's enum and array definition.

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 'compare' as the verb and specifies entities (companies or drugs). It distinguishes from siblings by advocating preference over sequential single-pack lookups, making purpose unambiguous.

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

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

Explicitly states when to use: for comparing 2–5 entities, with examples like 'which is bigger'. It advises 'ALWAYS PREFER over sequential single-pack lookups', providing clear usage context and implicitly excluding single-entity queries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds beyond: explains return of verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, explicit gaps[], and expected timing (15-60s). No contradiction.

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

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

Well-structured with core value front-loaded. Slightly verbose but every sentence adds value. Could tighten length slightly without losing clarity.

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

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

Given complexity, absence of output schema, and rich annotations, the description is thorough: explains return format (findings packet with evidence, gaps), prerequisites, and timing. Sufficient for agent to understand invocation and expected output.

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. Description adds detail: depth enum values mapped to facet counts (quick=3, standard=5, thorough=8 with paid plans), and emphasizes question should be broad/multi-part. Adds significant 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 performs 'grounded multi-source research in ONE call', decomposing questions and routing to tools. It distinguishes from sibling 'ask_pipeworx' and specifies the types of questions it handles (broad/multi-part).

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 provides when to use (broad or multi-part questions) and when not to (use ask_pipeworx for single lookups). Also mentions account requirements and paid plan for depth:thorough.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint false) already indicate a safe, non-destructive tool. The description adds that it returns schemas and examples, and that results are ready to call directly. No contradictions; additional behavioral context is provided.

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 (4-5 sentences), front-loaded with the core purpose, and every sentence adds essential information: purpose, usage guidance, return value, and a 'call first' directive. 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?

Despite no output schema, the description fully explains what is returned (top-N tools with names, descriptions, and full input schemas with examples) and notes that results are directly callable. No gaps remain.

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

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

Schema description coverage is 100% with 6 parameters documented. The description adds value by noting aliases (task, q, description, search) and providing examples of natural language queries. This goes beyond the schema alone.

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

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

The description explicitly states the verb 'Find tools' and the resource (tools). It lists many concrete data and task types (SEC filings, FDA drugs, etc.), making the scope clear. It distinguishes from siblings by positioning itself as the tool to discover what tools exist, unlike other tools that perform specific tasks.

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

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

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance. Missing explicit when-not-to-use or alternatives, but the directive is strong enough for most contexts.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds valuable behavioral context: parallel fan-out across sources, soft-fail for patents ('USPTO PatentsView API sunset May 2025 — soft-fails until reactivated'), and GDELT→GNews fallback for news. 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?

Description is relatively long but well-structured: starts with example queries, states purpose, lists detailed return fields. Every sentence adds value (e.g., patent status, news fallback). Could be slightly tighter but not excessive.

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

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

Tool is complex (multi-source parallel call, multiple output fields). No output schema, so description must cover return structure. It does: CIK, recent filings with pipeworx URIs, fundamentals sorted, patents with status, news with fallback, LEI. Also notes limitations (only company type supported, names not). Complete 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 covers both parameters with 100% coverage. Description reinforces that 'value' is ticker or CIK (zero-padded) and reiterates that names are not supported. It adds the example of zero-padded CIK, which is slightly beyond schema, but mostly echoes 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 opens with concrete user queries ('Tell me about X', 'brief me on Tesla') and explicitly states 'full cross-source profile of a US public company in ONE parallel call.' It lists specific outputs (CIK, filings, fundamentals, patents, news, LEI) and clearly distinguishes from siblings like 'resolve_entity' and 'compare_entities.'

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

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

Explicitly advises: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' Also clarifies name handling: 'names not supported (use resolve_entity first if you only have a name).' Provides explicit when-to-use and when-not-to-use guidance.

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

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

Description aligns with annotations (destructiveHint=true, idempotentHint=true). No contradictions. Does not add extra detail beyond annotations but adequately communicates 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?

Three sentences with no wasted words. Front-loaded with action, then usage conditions, then sibling relation.

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

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

For a simple delete tool with one parameter and good annotations, the description covers purpose, usage context, and relationships. 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 has 100% coverage for the single parameter 'key'. The description repeats the parameter's purpose ('Delete a previously stored memory by key') but does not add additional semantic information beyond the schema.

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

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

Clearly states the verb 'Delete' and resource 'previously stored memory by key'. Distinguishes from siblings by mentioning 'Pair with 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 provides when to use: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' Also references alternatives.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds specific behavioral details: fetching the page, extracting content, and outputting a text blob. This provides valuable context beyond annotations.

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

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

Three sentences efficiently cover purpose, process, and use cases. Front-loaded with the most important information. No redundant or unnecessary text.

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

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

The description explains the output format (standard llms.txt markdown text blob) and provides use cases. For a simple tool with two parameters and no output schema, this is sufficient. Could elaborate slightly on exact format but adequate.

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 main description mentions 'any URL' but does not add meaningfully to the parameter descriptions already present in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, explaining the process (fetches page, extracts title/description/key links, emits standard format). It distinguishes itself from siblings by focusing specifically on llms.txt generation.

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 three use cases (client indexing, own project drafting, competitor auditing), providing clear context for when to use. It does not explicitly state when not to use, but the use cases are sufficient.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds value by listing exact return fields (id, type, params, created_at, last_fired_at, fire_count), providing transparency beyond what annotations offer.

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

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

Two sentences: first sentence states purpose and output, second provides usage guidance. Front-loaded and every sentence adds value with no redundancy.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description covers purpose, output fields, and usage. Could clarify that 'active' is default behavior but parameter allows inactive.

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% for the single parameter 'include_inactive'. Description adds no extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states 'List the caller's active subscriptions' with specific verb and resource. It distinguishes from sibling tools 'subscribe' and 'unsubscribe' by focusing on reading existing subscriptions.

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

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

Explicitly tells when to use: 'review what you're monitoring before adding more or to find an id to cancel'. Provides clear context but does not explicitly state when not to use or list alternatives beyond implication.

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

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

Beyond the minimal annotations, the description discloses rate limits (5 per identifier per day), that it's free and doesn't count towards quota, and how feedback is processed (daily digests, roadmap impact). 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?

Six sentences with no waste. Each sentence adds unique value: purpose, use cases, what to avoid, rate limits, and context. 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 the tool's simplicity (3 params, no output schema), the description fully covers how to provide feedback, constraints, and expectations. No gaps remain for agent 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%, so baseline is 3. The description adds meaning by explaining enum values for type, advising on message content (specific, 1-2 sentences, 2000 chars max), and clarifying context fields. 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 states a clear verb-resource pair: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It uses specific categories (bug, feature, etc.) and distinguishes from sibling tools like ask_pipeworx or discover_tools by its unique feedback 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?

Explicitly tells when to use: 'Use when a tool returns wrong/stale data...' and what not to do: 'don't paste the end-user's prompt.' Also includes rate limit and quota info, which guides usage.

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

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

Annotations already cover readOnly, openWorld, idempotent, not destructive. Description adds valuable context: data source (CF analytics-engine), no PII, caching behavior (5min-1h). 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?

Very concise: four sentences cover purpose, use cases, and behavioral notes. Bullet points are clean. No redundancy with schema or annotations.

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 essential behavioral context and use cases. However, since no output schema exists, the description could be more explicit about the exact return format (keys, data types). Still sufficient for most agents given simplicity.

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

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

Only one parameter with 100% schema coverage and enum description. The description adds context about how to choose a window (short vs long for different purposes), which goes beyond the schema's enum labels.

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

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

Clearly states it returns top tools, top packs, and total call volume over a recent window. Includes specific use cases that differentiate it from sibling tools like 'discover_tools' or 'ask_pipeworx'.

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

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

Lists three concrete use cases for when to use this tool, and explains the trade-off between different window lengths. Does not explicitly mention when not to use or name alternatives, but the guidance is clear and actionable.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint true; description adds critical behavioral context: required parameter, monotonicity and partition checks, fill check (realizable_edge_pp ≤ 0 means no trade), Jaccard similarity threshold, and placeholder filter. No contradictions with annotations.

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

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

The description is fairly long but efficiently packs essential information. It uses bold for key requirements and organizes content logically. Slight reduction could be possible, but every sentence contributes to understanding.

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

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

Given complexity (two modes, multiple checks, fill verification), the description thoroughly covers behavior, inputs, outputs (opportunities array, partition_check, fill check details), and edge cases (placeholder slugs, similarity threshold). No output schema exists, so description adequately handles return values.

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

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

Schema coverage is 100%, but description adds substantial value: examples for event slugs and topic seed questions, explanation of cross-event mode, and clarification that full URLs work. It also elaborates on the partition check and fill check 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 identifies arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes two modes (event and topic) with specific examples, and differentiates it from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

It explicitly states 'REQUIRES one of `event` OR `topic` — call with no args fails.' It recommends `event` mode for specific markets and explains when to use each. It also directs users to polymarket_fill_risk for custom sizing, providing alternative guidance.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive. Description adds caching behavior (1h KV-level), Fed bets exclusion, and edge_pp_net after slippage. 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?

Dense and informative, each sentence adds value. Well-structured with sections for model families, parameters, and response. However, could be more concise given length.

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

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

Despite no output schema, description thoroughly explains response structure (by_segment, fed_candidates, _diagnostics) and segment models. Covers all 9 parameters and their interplay. Complete for a complex tool.

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

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

Schema coverage is 100%, baseline is 3, but description adds significant value: explains why min_kelly filters small opportunities, notes slippage assumptions and Polymarket zero fees, clarifies max_spread_pp for tight books, details min_liquidity interaction with book depth, and explains min_partition_leg_kelly handling of Kelly at parent vs leg level.

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

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

Clearly states the tool scans Polymarket markets for opportunities where Pipeworx data disagrees with market price. Differentiates from siblings like `polymarket_arbitrage` by including model-driven and concentrated longshots, as evident from the description's segment list.

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

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

Provides clear context: 'Built for what should I bet on today' and mentions tradeable-edge knobs. However, does not explicitly state when to avoid this tool versus alternatives like `bet_research` or `polymarket_arbitrage`.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description goes beyond by detailing limits (60-day TTL, snapshot start date, decay calculation from daily closes, not intraday). 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 long but every sentence adds value. It front-loads the core purpose and then details response fields. Could be slightly more concise, but no unnecessary repetition.

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 provides a comprehensive breakdown of the response structure (tracked[], expired[], snapshot_dates[]) with field meanings and examples. Combined with parameter explanations and limits, the description is fully self-contained.

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

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

Schema coverage is 100% and schema descriptions are adequate. The tool description restates defaults and allowed values for days but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: analyzing edge persistence and decay using daily snapshots. It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes this from a simple current-edge tool like polymarket_edges by framing it as telemetry over time.

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 args and their defaults, and outlines the response structure and limits. However, it does not explicitly contrast when to use this tool versus its sibling polymarket_edges, which could leave the agent uncertain about choosing between them. The context is clear but lacks direct alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds valuable behavioral context beyond annotations, such as walking the ladder, returning fill details, and warning about forced directional risk. No contradiction with annotations.

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

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

The description is dense but well-structured with sections for single-market and basket modes. It front-loads the purpose and immediately clarifies required fields. While long, every sentence serves a purpose; slight verbosity is justified by the tool's complexity.

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

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

Despite lacking an output schema, the description enumerates return fields (top_of_book, vwap_fill_price, slippage_pp, shares_filled, etc.) for both modes, including per-leg detail and forced_directional_risk. Given the tool's complexity (4 params, two modes, no required params), the description covers all necessary aspects.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds extra meaning: it explains size_usd semantics for both modes (max spend vs target proceeds; settlement notional), side defaults and auto-detect logic for basket, and the role of market vs event. This is additive value beyond the schema.

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

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

The description starts with a specific verb-resource pair: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market and basket modes, which are unique among sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

The description explicitly states when to use the tool: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround not capturable on thin books, partial fills create directional risk), providing clear context and exclusion criteria.

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 richly details behavioral traits beyond the annotations (readOnlyHint, etc.). It explains the response structure, compatibility warning conditions (including skipped cross-type/subtype counters), temporal alignment, and the reality that many pre-mapped topics are not tradeable. This provides a complete picture of tool behavior and edge cases.

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

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

The description is well-structured with a clear opening, separate paragraphs for modes, response fields, and safety notes. While it is lengthy, almost every sentence adds value. Some repetition (the final warning echoes earlier content) is minor; overall it is efficient for the complexity it conveys.

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 is exceptionally complete given the tool's complexity: it explains input modes, output fields, safety scenarios, and temporal considerations. Without an output schema, this description fully compensates by detailing what the response contains and how to interpret edge cases. No gaps are evident.

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

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

The schema already provides 100% coverage with descriptions for each parameter. The tool description adds further meaning by explaining the two modes, listing valid topic values, and noting that explicit tickers override the topic. This extra context, while not strictly necessary given the schema, enhances understanding.

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

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

The description clearly states the tool calculates cross-venue spreads between Kalshi and Polymarket, with two modes (topic shortcuts and explicit tickers). It defines the output as matched spreads. However, it does not explicitly differentiate from the sibling 'polymarket_arbitrage', missing an opportunity to clarify when to use which.

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 the tool (for cross-venue comparison) and explains the two operational modes. It warns that most pre-mapped topics return compatibility warnings, implying limited usability. However, it lacks explicit when-not-to-use directives or pointers to alternative tools 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to re-state safety. It adds value by describing the return format (country codes and probabilities), which goes beyond annotations.

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

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

The description is two sentences, front-loaded with the core purpose and output format. Every word contributes meaning, with no redundancy or fluff.

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

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

For a simple tool with one parameter, strong annotations, and an output schema (referenced as existing), the description provides enough context (output format, use case). Minor omission: no mention of handling edge cases like nonexistent names, but overall complete.

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

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

The single parameter 'name' is fully described in the schema with a clear description. With 100% schema coverage, the description adds no further semantic value, warranting a 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 predicts likely nationalities from a first name, specifying the output format (up to 5 country codes with probabilities). This distinguishes it from sibling tools like batch_predict or compare_entities which serve different purposes.

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 directly states when to use the tool: 'Use when inferring someone's origin from their given name.' While it doesn't explicitly exclude alternatives, the context and simplicity make it clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds valuable context: scoping to identifier (anonymous IP, BYO key hash, account ID) and the listing behavior when key is omitted. 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?

Two sentences with no wasted words. The main purpose is front-loaded, followed by examples and scoping. Every sentence adds value.

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

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

For a simple read-only tool with one optional parameter, the description covers purpose, usage context, scoping, and relationship to siblings. The return behavior (value or list) is implied. No output schema is needed given the simplicity.

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

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

Schema coverage is 100%, and the description of the 'key' parameter matches the schema. The description adds the nuance that omitting the key triggers listing all keys, which is helpful but the schema already implies optionality. 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 begins with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and includes the alternative behavior of listing all keys when the argument is omitted. It clearly distinguishes itself from sibling tools 'remember' and 'forget'.

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

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

The description provides clear context on when to use the tool: 'to look up context the agent stored earlier' with concrete examples (ticker, address, notes). It also mentions pairing with remember/forget, but does not explicitly state when not to use it or list alternatives beyond siblings.

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 contradicts the readOnlyHint annotation by stating mark_read:true flags returned events as read, which modifies persistent state. This is a clear side effect not allowed under readOnlyHint=true.

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?

Dense but clear, front-loaded with purpose, then filtering options, then behavioral details. Every sentence adds value, though slightly lengthy.

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 fields, filtering, mark_read behavior, polling suitability, and an alternative access method. Lacks explanation of default limit or pagination, but otherwise complete given no output schema.

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

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

Adds meaning beyond schema descriptions with examples (e.g., 'sec_8k' for type) and explains the effect of mark_read on future calls. Schema coverage is 100%, but description still enriches parameter understanding.

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

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

The description clearly states the tool pulls fired events from the subscription feed, returns recent alerts with specific fields (source, citation_uri, payload), and distinguishes from sibling tools like list_subscriptions and subscribe by focusing on retrieval rather than management.

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

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

Provides explicit filtering options (type, since), explains mark_read behavior, mentions polling is fine, and gives an alternative endpoint (GET registry.pipeworx.io/alerts.json) for scripts/dashboards, guiding when to use this tool vs 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?

Discloses multiple data sources (SEC EDGAR, GDELT→GNews fallback, USPTO with soft-fail), parameter behavior (ISO date or relative shorthand), and return structure (grouped changes with citation URIs). Annotations confirm read-only, idempotent, non-destructive, no contradiction.

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

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

Highly informative and well-structured with use-case examples first. Slightly verbose but every sentence adds value; could trim minor 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?

Comprehensively covers all aspects: multiple sources, fallback logic, parameter format options, soft-fail behavior, return format, and links to alternative tool. No output schema, but description suffices.

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?

Adds meaning beyond schema: explains that 'since' accepts ISO dates or relative shorthand (e.g., '30d'), 'value' can be ticker or CIK, and 'type' is limited to 'company'. Schema coverage is 100% but description enriches understanding.

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

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

The description clearly states the tool provides a 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It uses specific examples like 'What's new with X' and differentiates from sibling tool 'entity_profile'.

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

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

Explicitly tells when to use ('latest on Y', 'updates on Acme') and when not to ('Use entity_profile instead when you want the static profile'). Provides clear guidance on 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 (idempotentHint=true, readOnlyHint=false, destructiveHint=false), the description adds persistence behavior: authenticated vs anonymous retention, 24-hour expiry. This provides useful context beyond what annotations offer.

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

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

The description is concise: 4 sentences, front-loaded with purpose and usage. 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 write tool with no output schema, the description covers purpose, usage context, behavioral details (persistence, expiry), and companion tools (recall, forget). It is fully informative.

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 key and value. The description adds examples of keys and reinforces that value is 'any text', but does not significantly augment 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 uses clear verbs ('save', 'store') and specific resource ('data the agent will need to reuse later'), and distinguishes from sibling tools like recall and forget. It explicitly states the scope (key-value pair, scoped by identifier).

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 ('when you discover something worth carrying forward') and mentions alternatives ('pair with recall...forget'), but does not explicitly state when not to use or provide 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 indicate readOnly, idempotent, non-destructive behavior. The description adds value by revealing internal cascading ('replaces 2-3 manual lookups') and provides context on what each type returns (ticker, CIK, RxCUI, etc.). 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?

Every sentence is purposeful. It starts with common user queries, states the purpose, lists supported types with detailed returns, and ends with an efficiency note. No fluff, well-organized.

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

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

Given no output schema, the description thoroughly covers return values for both types and input expectations. Lacks details on error handling or edge cases (e.g., CIK digit length), but overall adequate for an AI agent.

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

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

Schema descriptions are present (100% coverage), but the description adds significant meaning: explains each type's return fields, accepted input formats (ticker, CIK, name for company; brand/generic for drug), and auto-disambiguation. This goes well beyond what the schema provides.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers for 'company' and 'drug' types, using specific verbs like 'resolve' and 'look up'. It distinguishes from sibling tools by its unique function—no sibling does entity resolution.

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 instructs 'Use FIRST whenever you have a name but need an ID.' This provides clear context on when to use the tool. Lacks explicit 'when not to use' or alternatives, but the strong directive compensates.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating safe and idempotent behavior. The description adds valuable context: it probes with ai_visibility_check, ranks results, and returns score, confidence, signal density per entity. 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?

Four sentences, front-loaded with purpose, then action, use case, output. No redundant information. Every sentence is informative and earns its place.

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

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

Given the tool's complexity (comparative analysis across entities, multiple models, optional context) and the absence of output schema, the description provides sufficient detail: it explains what probes are called, ranking, and specific output fields (score, confidence, signal density). No gaps remain.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning: explains that 'entities' first is the subject, 'context' disambiguates, 'models' defaults to workers-ai, and '_apiKey' is needed for anthropic. This goes 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: to compare AI visibility across multiple entities side-by-side, using ai_visibility_check, ranking by score, and surfacing most/least recognized. It distinguishes from the sibling ai_visibility_check by focusing on comparative analysis.

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

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

Explicitly states use case: competitive AI-marketing audits. Mentions that the first entity is the subject and rest are competitors. Implicitly advises against using for single entity checks (use ai_visibility_check instead), but lacks explicit when-not-to-use or alternative references.

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

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

The description adds meaningful behavioral context beyond annotations: it discloses partial failure degradation, bundlephobia's first-version latency (5-30s), and the sources_failed field. This complements the readOnlyHint, openWorldHint, and idempotentHint annotations without contradiction.

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

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

The description is somewhat long but front-loaded with the core purpose. Every sentence provides necessary detail for correct usage, and the structure is logical. No wasted words, but could be slightly tightened.

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

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

Despite no output schema, the description fully explains the return structure (summary block, per-advisory detail, links, alternative versions). It covers ecosystem scope, failure modes, and latency, making it complete for an agent to use correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: acceptance of scoped packages ('@types/node'), version defaults to latest, and NPM-only scope. This adds value beyond the schema.

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

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

The description uses specific verb ('scan') and resource ('npm package'), clearly stating it's a composite check across deps.dev and bundlephobia. It distinguishes itself from sibling tools by its unique functionality.

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

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

The description explicitly states when to use ('is X safe / popular / small' or 'what does adding lodash cost me') and when not to use ('NPM ecosystem only in v1; PyPI/Maven/Cargo/Go fall under deps.dev:version directly'), providing clear context and alternatives.

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

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

The description adds significant behavioral details beyond the annotations: embedding model (BGE-base-en), windowing approach (500-char overlapping windows), similarity measure (cosine), character cap (200K chars with truncation flag), and return format (passages with character offsets and similarity scores). No contradiction with annotations.

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

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

The description is concise yet comprehensive, with a single well-structured paragraph. Each sentence contributes meaningful information: purpose, usage guidance, technical details, and pairing advice. No wasted words.

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

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

Despite no output schema, the description fully explains what the tool returns (passages with offsets and scores), how it works (embeddings, windows, cosine), its limitations (200K char cap), and its role in a workflow (pairing with ask_pipeworx_grounded). 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 coverage is 100%, so baseline is 3. The description adds value by providing examples for the query parameter ('supply-chain risk', 'fiscal year 2024 revenue'), specifying default and range for limit (1-20, default 5), and clarifying the text input's max length. This enhances understanding beyond the schema.

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

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

The description clearly states the tool's purpose: 'Semantic search INSIDE a fetched record.' It uses specific verbs and resources, gives concrete examples (SEC 10-K, article), and distinguishes from sibling tools like ask_pipeworx_grounded by noting how they pair together.

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 when the record is too big to cram into the prompt' and describes when to use the tool versus alternatives. It also mentions pairing with another tool (ask_pipeworx_grounded), providing clear contextual guidance.

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

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

The description adds rich behavioral context beyond annotations: OAuth requirement, phone verification, daily SMS cap, webhook signing details. Annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true) are not contradicted.

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 purpose and structured logically. It is slightly long but every sentence adds value for a complex tool. Could be more concise but not wasteful.

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 (3 parameters, nested objects, multiple types, no output schema), the description covers prerequisites, type-specific filters, delivery options with constraints, and return value (subscription id). No gaps.

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

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

Despite 100% schema coverage, the description adds significant meaning: explains each type's parameters with concrete examples (e.g., sec_8k items:["5.02"] = officer change) and full delivery channel details including webhook HMAC.

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' - a specific verb+resource. 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?

The description explicitly states prerequisites (Pipeworx OAuth account, not anonymous/BYO) and provides detailed examples for each subscription type and delivery channel. It lacks explicit 'when not to use' but the context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false, so the safety profile is clear. The description adds value by explaining the return structure (category-bucketed example questions with exact tool + argument shape) and that it draws from the live catalog, but no additional behavioral details beyond annotations.

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

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

The description is dense but well-structured, front-loading purpose with alternative phrasings. It efficiently covers output and usage without redundancy, though some alternative phrasings could be trimmed for even greater 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 compensates by detailing the return type (category-bucketed example questions with exact tool + argument shape). It covers the live catalog source and the optional topic filter, making the tool's behavior sufficiently complete for an AI agent.

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

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

Schema coverage is 100%, with the optional 'topic' parameter well-described. The description adds context that omitting topic yields a full spread, which goes beyond the schema's focus areas list. This adds meaningful usage guidance.

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 as an onboarding entry point that returns example questions across categories. It includes alternative phrasings like 'What can I ask Pipeworx?' and specifies the output format, distinguishing it effectively from siblings by framing it as the first tool to use.

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

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

The description explicitly advises to 'Use this FIRST when you do not yet know what Pipeworx can do for you' and explains when to call with no arguments vs. with a topic. It does not explicitly list when not to use, but the 'first' implication provides clear contextual 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?

Discloses that the row is deactivated (not deleted) and ownership enforcement, which adds value beyond annotations. Annotations already indicate idempotent and non-destructive; description elaborates on the deactivation 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 fluff, front-loaded with action and resource. Every sentence provides essential information.

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

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

Given the simple tool (one required param, no output schema, no nested objects), the description covers purpose, constraints, and behavioral nuance completely.

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

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

Schema already fully describes the 'id' parameter with required details; description does not add significant new meaning beyond what the schema provides.

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

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

Clearly states the verb 'Cancel a subscription' and the resource, with explicit ownership enforcement and deactivation behavior. Distinguishes from sibling 'subscribe'.

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

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

Describes when to use (cancel own subscription) and includes constraint (ownership enforcement) but does not explicitly state when not to use or name alternatives.

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

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

Annotations already indicate read-only, idempotent, open-world behavior. The description adds valuable context: it returns a verdict with structured data, a citation, and percent delta, and it replaces multiple sequential calls. No contradictions.

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

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

The description is somewhat lengthy but well-structured: first paragraph captures query phrases and general use, second paragraph adds technical scope and output details. Front-loaded with purpose.

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

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

Given the single parameter and lack of output schema, the description thoroughly covers behavior, output format, and limitations, making it complete for an agent to decide when and how to use it.

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

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

The schema covers the single claim parameter with a description. The tool description enriches it by specifying supported claim types (company-financial) and providing example claims, adding value beyond the schema.

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

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

The description clearly defines the tool as natural-language claim verification with specific examples (e.g., 'Is it true that...', 'fact check'), and it uniquely targets company-financial claims via SEC EDGAR, distinguishing it from sibling tools like deep_research or compare_entities.

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

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

The description explicitly states when to use: 'whenever the agent needs to check whether something a user said is factually correct.' It also specifies the scope (company-financial claims in v1), implying limitations but not explicitly stating 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.