College Scorecard

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds valuable context: it probes external LLMs (Workers AI free, Anthropic pay-as-you-go), explains key handling, and outlines return structure. 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 four sentences, front-loaded with the primary action and output. Every sentence adds distinct information: purpose, model options, return fields, and 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?

Despite lacking an output schema, the description explicitly lists return fields (score, confidence, signals, raw_response per model plus combined view). It covers all parameters and explains edge cases (BYO key, context disambiguation). For a tool with this complexity, the description is complete.

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

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

Schema coverage is 100% with all parameters described. The description adds value beyond the schema by explaining default model behavior, the relationship between models and _apiKey parameters, and the purpose of the context parameter.

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

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

The description clearly states the tool probes LLMs for what they know about an entity and scores visibility (0-100). It specifies the default model and option to add Anthropic with BYO key. This distinguishes it from siblings like compare_entities or deep_research, 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 explicitly says 'Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring,' giving clear context. However, it does not mention when not to use this tool or suggest alternatives among siblings, which would elevate it to a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds context about routing to 5,245 tools, filling arguments, and returning structured answers with pipeworx:// URIs, 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?

Description is comprehensive but slightly long. However, each part serves a purpose: positioning, scope, usage guidance, examples, and sibling differentiation. Front-loaded with key recommendation.

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 (6 parameters, routing to many sources), the description covers purpose, usage, return format, and comparisons with siblings. No output schema, but return format is described. Fully 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% and describes all aliases. Description adds value by listing example questions and specifying the kinds of queries that work, which helps users formulate the input correctly.

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

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

Description clearly states the tool routes questions to many sources for factual data, distinguishes itself from web search and sibling tools, and provides specific examples of 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?

Explicitly says 'PREFER OVER WEB SEARCH', gives when to use (any factual question), and when to step up to ask_pipeworx_grounded or deep_research. Provides examples and sets as default entry point.

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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds context that it is a full working router but experimental, with candidate routing improvements tested live. 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 informative but slightly verbose. Key information is front-loaded (beta, identical router, candidate status). It could be more concise, but overall structure is acceptable.

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

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

Given the complexity of a beta router with many tools, the description covers current state, fallback behavior (none), and how it compares to stable routing. No output schema exists, but the description notes identical response shape, which is sufficient.

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

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

Schema coverage is 100% with all parameters documented as aliases for 'question'. The description does not add new parameter details beyond the schema, so it meets the baseline 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 it is a beta version of ask_pipeworx, an identical universal router with the same tools and arguments. It distinguishes itself from siblings like ask_pipeworx (stable) and ask_pipeworx_grounded by emphasizing it is the experimental edge for routing improvements.

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

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

Explicitly states when to use: 'when you want the newest routing'. Mentions that currently no candidate is active so it matches ask_pipeworx exactly, and that results are compared to the stable router to decide merges. This provides clear context for usage and differentiation.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds rich behavioral detail: returns specific structure with evidence, confidence, refusal reasons. Clearly states it extracts answer ONLY from tool result and costs an 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?

Description is efficiently written, front-loaded with purpose. Six sentences, each adding value. Could be slightly trimmed but still focused and clear. No redundancies.

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

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

Given no output schema, description fully explains return structure (answer, evidence, confidence, source, fetched_at, refusal_reason) and all possible refusal reasons. Complex tool with many parameters and annotations, yet description leaves no ambiguity.

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%. The description mentions aliases but that is already captured in schema. No additional semantics beyond what schema provides. Baseline 3 is appropriate.

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

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

Description explicitly states it is a 'Hallucination-resistant answer mode for high-stakes reads.' It clearly distinguishes from sibling ask_pipeworx by contrasting casual vs high-stakes use. The verb 'extracts' and resource 'answer' are specific.

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

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

Provides explicit context: 'Use whenever an answer will be quoted, cited, or acted on...' and lists examples. Also states when not to use: 'prefer ask_pipeworx for casual lookups.' Covers both use and exclusion.

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=true, idempotentHint=true, non-destructive) already signal safety. The description adds extensive behavioral context beyond annotations: low-confidence short-circuits suppress analysis, closed markets return a blocking status, wide-spread markets carry illiquidity notes, resolution-rule risk is parsed from cancellation rules, parent event extraction is detailed, news fallback fields are documented. 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 very long and detailed, with structured sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES). While the structure helps readability, it contains redundant explanations and could be more concise without losing key 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?

No output schema exists, so the description must fully explain return values. It does: details result.market fields (best_bid/best_ask/liquidity, etc.), result.analysis (model_probability/edge_pp/kelly_fraction, 24h-move warning), result.evidence keyed by source, market_match_confidence levels, parent_event extraction, news fallback fields, and safety/blocking conditions. Given the tool's complexity (classifiers, fan-outs, edge cases), the description is remarkably thorough.

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

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

Schema coverage is 100% (all 3 parameters have descriptions). The description adds meaning: 'market' can be slug, URL, or question; 'depth' quick vs thorough; 'include_raw' explains when to use true vs false. This goes beyond the schema's basic type/enum definitions, but schema already provides adequate descriptions.

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

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

The description starts with a clear verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and outputs (evidence packet, comparison), distinguishing it from sibling tools like polymarket_arbitrage or polymarket_edges which have narrower scopes.

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

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

Explicit usage scenarios are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' The description also details various edge cases (low-confidence, closed markets, wide spreads) that guide when to trust the output. However, it does not explicitly contrast with sibling tools like ask_pipeworx or deep_research, so missing some when-not-to-use guidance.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: for companies it pulls specific financial metrics from SEC EDGAR/XBRL with correct fiscal-year handling; for drugs it pulls FAERS data, trial counts, and FDA approvals. It also describes output format (paired data with citation URIs) and sorting by primary metric.

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 densely informative yet concise: it starts with query examples, gives clear usage instruction, explains data sources and behavior, and ends with efficiency claim. Every sentence serves a purpose with no fluff.

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

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

With two parameters and no output schema, the description covers all necessary information: entity types, data sources, behavioral handling (fiscal years), result ordering, and output format. It leaves no significant gaps for an agent to correctly invoke the tool.

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

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

Schema coverage is 100% and includes enum descriptions for 'type' and description for 'values'. The description adds extra meaning by explaining what data each type returns (company vs drug) and giving concrete examples (tickers/CIKs for company, drug names). However, the schema already covers basic constraints, so the description adds moderate incremental value.

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

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

The description starts with explicit examples of natural language queries ('Compare X and Y', 'which is bigger'), clearly identifies the verb 'compare' and the resources (companies or drugs), and distinguishes itself from sibling tools like 'entity_profile' by stating it replaces sequential single-pack lookups.

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

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

The description explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and quantifies efficiency ('Replaces 8–15 sequential lookups'), giving clear when-to-use and when-not-to-use guidance.

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

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

Annotations already indicate safe, read-only, idempotent behavior. The description adds extensive behavioral context: account requirements, free vs paid plans, expected latency (15-90s), return format (findings with evidence, gaps, contradictions, hop field, citation URIs), and semantic excerpting. 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 lengthy but every sentence adds unique information. It is front-loaded with critical account requirements and alternatives. While it is a single dense paragraph, the structure is logical: purpose, prerequisites, then detailed behavior. Could be slightly more concise, but content justifies 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?

With only 2 parameters and no output schema, the description provides all necessary context: purpose, usage guidelines, behavioral details (including time estimates), parameter semantics, and return format. It fully compensates for the lack of an output schema.

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

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

Schema coverage is 100%, so baseline is 3. The description adds significant value by explaining the depth parameter's impact (number of facets, gap recovery, contradictions scan) and that question accepts natural language, broad/multi-part queries. However, the schema already describes the enum values adequately.

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

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

The description clearly states the tool's purpose: grounded multi-source research across 1369 structured data sources in one call. It distinguishes from siblings like ask_pipeworx, which is for single lookups or current news.

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

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

Explicitly states when to use (broad/multi-part questions over structured data) and when not to (single lookup, breaking news). Provides alternatives: ask_pipeworx for single lookups and current news. Also discusses second-hop iteration for different depths.

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, non-destructive. Description adds behavioral detail: returns top-N results ready to call with full schemas, no second lookup needed. 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 succinct, front-loads purpose, and every sentence adds value. No wasted words.

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

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

For a discovery tool with 6 params and no output schema, description fully explains what the tool does, what output contains (names, descriptions, schemas), and provides guidance on when to use it. No gaps.

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

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

Schema coverage is 100% with full descriptions. Description adds context about query aliases and natural language usage, but does not significantly extend meaning beyond schema.

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

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

Description clearly states the tool finds tools by describing data or task, lists specific domains (SEC, FDA, etc.), and explains output includes schemas ready to call. Distinguishes from sibling tools which are more specific.

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

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

Explicitly says to use when browsing/discovering tools and to call FIRST when many tools are available. Does not explicitly state when not to use or name alternative tools, but context suggests it's the discovery tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false. The description adds significant context: data sources used (SEC EDGAR, XBRL, USPTO, GDELT→GNews, GLEIF), return format (fields listed with URIs and sorting), and soft-fail for patents. This goes beyond annotations without contradiction.

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

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

The description is dense but well-structured: it starts with example queries, states the core purpose, lists data sources, enumerates return fields with details, and ends with parameter format. Every sentence adds value; there is no redundancy or filler.

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

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

The tool returns a complex profile without an output schema, so the description must fully document the return value. It does so comprehensively: lists all fields (cik, company_name, recent_filings with URIs, fundamentals with sorting, patents with status, news via fallback, LEI). This is 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 coverage is 100% with detailed descriptions for both parameters. The description repeats the schema text for 'value' and 'type' without adding new semantics. No additional parameter guidance is provided beyond what the schema already states.

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: 'full cross-source profile of a US public company in ONE parallel call.' It provides specific verbs (profile, brief, get rundown) and resources (company, ticker, CIK) with examples. It distinguishes from siblings by advising preference over chaining single-pack lookups and referencing resolve_entity for 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?

The description explicitly states when to use ('ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view') and when not to use ('names not supported — use resolve_entity first if you only have a name'). It also lists fallback behavior (e.g., patents soft-fail, news fallback from GDELT to GNews).

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

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

Annotations already mark destructiveHint=true and readOnlyHint=false. The description adds context about clearing sensitive data, which aligns with destructive behavior but does not disclose additional traits beyond annotations.

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

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

Two concise sentences: first states purpose, second provides usage context. No redundant information.

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

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

For a simple tool with one parameter, no output schema, and clear annotations, the description fully covers purpose and usage context.

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

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

Schema coverage is 100% with the single parameter 'key' well-described. The description adds no new semantic meaning beyond what the schema already provides, warranting the baseline score.

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 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes from sibling tools like 'remember' (store) and 'recall' (retrieve).

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 usage contexts: stale context, task completion, clearing sensitive data. Mentions pairwise usage with 'remember' and 'recall,' but lacks explicit when-not-to-use 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 readOnly, idempotent, openWorld, non-destructive. Description adds process details: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' Also notes output placement: 'ready to drop at site-root/llms.txt.'

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

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

Two concise sentences followed by a bullet list of use cases. Front-loaded with main purpose. Every sentence adds value without redundancy.

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

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

No output schema, but description fully explains output format ('standard llms.txt markdown format', 'single text blob') and process. Use cases cover practical applications. Complete for this tool's complexity.

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

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

Schema coverage is 100% with descriptions for both parameters. The tool description does not add new parameter information beyond what the schema provides; defaults and limits are already in schema. Baseline of 3 is appropriate.

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

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

The description clearly states the verb (Generate), resource (llms.txt file), and scope (for any URL), distinguishing it from sibling tools like ai_visibility_check. Example: 'Generate a production-ready llms.txt file for any URL'.

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

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

Provides explicit use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' Does not explicitly state when not to use, but use cases are clear and self-contained.

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, and openWorldHint=true. The description adds the list of returned data fields and the data source (College Scorecard). It does not add further behavioral context like rate limits or data recency, but given the rich annotations, the incremental value is moderate.

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

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

The description is a single sentence concisely stating the purpose, followed by a list of returned fields. No filler or redundancy; front-loaded with key 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's low complexity (2 simple parameters, output schema exists), the description, annotations, and schema together provide all necessary context. The description adds the return fields, which complements the output schema and ensures completeness.

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

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

Schema coverage is 100% with both parameters (id and _apiKey) described. The description mentions 'by its College Scorecard ID' which reinforces the id parameter but doesn't add new semantic detail 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 uses a specific verb 'Get' and resource 'specific college' with a clear identifier 'College Scorecard ID'. It lists key return fields (tuition, admission rate, etc.), distinguishing it from sibling tools like search_schools which likely search rather than fetch details.

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

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

The description implies usage when you have a specific College Scorecard ID and need detailed info. While it doesn't explicitly exclude alternatives or state when not to use, the sibling set includes search_schools, making the context reasonably clear. A score of 4 reflects the lack of explicit exclusions 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context: only active subscriptions are returned by default (scope of 'caller's'), the effect of the include_inactive parameter, and the exact response fields. 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?

Two sentences: first states purpose and output, second provides usage guidance. No wasted words. Front-loaded with essential information.

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

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

For a simple list tool with one optional parameter and no output schema, the description is complete. It explains what it does, what it returns, and when to use it. Lacks details on pagination/ordering but these are not critical for this minimal tool.

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

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

Schema coverage is 100% with one parameter (include_inactive) already described in the schema. The description does not add extra semantic meaning for the parameter beyond implying its effect on active vs. cancelled subscriptions. 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 'List the caller's active subscriptions' (specific verb+resource) and lists the returned fields (id, type, params, etc.). This distinguishes it from sibling tools like subscribe and unsubscribe.

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

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

The description gives explicit usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This directly informs when to use this tool versus alternatives (subscribe/unsubscribe).

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 are all false, so description carries the burden. It discloses that the tool sends data, is rate-limited to 5 per identifier per day, is free, and doesn't count against tool-call quota. No contradiction with annotations.

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

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

Three sentences that are well structured: first sentence states purpose, second gives usage scenarios, third adds behavioral constraints. Every sentence earns its place, no wasted words.

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

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

For a simple feedback tool, the description is complete. It covers purpose, usage, formatting instructions, and constraints like rate limits and quota impact. 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 description coverage is 100%, so baseline is 3. The description adds little beyond what's in the schema; it reinforces the enum meanings and message constraints but doesn't provide new parameter-level semantics.

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

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

The description clearly states the tool's purpose: to send feedback to the Pipeworx team. It specifies the verb 'tell' and resource 'Pipeworx team', and distinguishes itself from sibling tools by being the only dedicated feedback mechanism.

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

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

Explicitly states when to use: for bugs, feature requests, data gaps, or praise. Provides guidance on message format (describe in terms of Pipeworx tools/packs, avoid pasting user prompts) and mentions rate limits and free cost.

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

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

Annotations already declare readOnly, idempotent, not destructive. Description adds caching (5min-1h), data source (CF analytics-engine), privacy (no PII), and output structure (pack, tool, count). Rich behavioral context beyond annotations.

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

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

Four sentences, front-loaded with purpose, then bullet-like use cases, then technical details. No superfluous words; every sentence adds value.

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

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

For a simple read-only tool with one optional param and no output schema, the description covers purpose, use cases, data freshness, privacy, and return structure. An agent can confidently select and invoke correctly.

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

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

Only one parameter (window) with enum and description. Schema coverage is 100%. Description adds context that shorter windows show hot trends, longer show steady-state demand, adding meaning beyond schema.

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

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

Clearly states it returns trending tools/packs/volume on Pipeworx over a recent window. Distinguishes itself from sibling tools (e.g., ask_pipeworx, discover_tools) as a meta/trending tool.

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 explicit use cases: discovering hot data, confirming canonical choice, aligning use case with demand. No when-not-to-use or alternatives, but guidance is clear.

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

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

Beyond annotations (readOnlyHint, openWorldHint, idempotentHint), the description details internal algorithms (Jaccard similarity, partition filter with placeholder detection, fill check against CLOB depth). It fully discloses behavioral traits including rejection criteria and edge case handling, with no contradictions to annotations.

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

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

The description is lengthy but well-structured with clear sections for modes, filters, and responses. Every sentence adds value given the tool's complexity, but a slight reduction in technical detail could improve conciseness without losing clarity.

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

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

Despite the lack of an output schema, the description fully explains the response structure (opportunities array, partition_check with fields) and the fill check logic. It covers all modes, filters, and edge cases, and references a related tool for further use.

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

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

Schema coverage is 100% but the description adds significant meaning: explains how event slugs and topic strings are interpreted, provides examples, and describes the underlying search and analysis logic for each parameter. This goes well beyond the schema descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities via monotonicity violations and partition-sum checks on Polymarket. It identifies three distinct modes (no-args trending scan, event-specific, and cross-event topic) and distinguishes itself from siblings like polymarket_edges and polymarket_fill_risk.

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

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

The description provides explicit when-to-use guidance for each mode: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic (for cross-event scanning)'. It also advises against trading when realizable_edge_pp ≤ 0 and points to polymarket_fill_risk for custom sizing.

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

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

The description extensively discloses behavioral details beyond annotations: caching (cached 1h), diagnostics for empty segments, edge computation methodology, Fed bets exclusion, and tradeable-edge knobs. Annotations already declare read-only, idempotent, non-destructive, and the description adds significant transparency.

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

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

The description is well-structured with clear sections (model families, response structure, knobs) and front-loaded with the core purpose. While it is lengthy, every sentence adds value; no redundancy. Could be slightly more concise but effective.

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

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

Given the tool's complexity (9 parameters, no output schema), the description is remarkably complete. It explains all three model families, response structure, diagnostics, caching, and caveats. Without an output schema, this description provides sufficient context for an agent to use and interpret results.

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

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

The input schema has 100% description coverage, so the baseline is 3. The description adds some context for parameters like min_partition_leg_kelly, but the schema itself already provides clear explanations. No additional semantic value beyond what the schema offers.

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: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It further specifies the use case ('what should I bet on today') and distinguishes from sibling tools like polymarket_arbitrage by focusing on Pipeworx data and opportunity discovery without paging.

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 usage context: agents can discover opportunities without paging, and it explains knobs (e.g., min_liquidity, max_spread_pp) that help refine usage. However, it does not explicitly mention when not to use this tool or list alternatives, though the context implies when it is appropriate.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and no destructive behavior. The description adds substantial behavioral context beyond these annotations: details on response structure (tracked, expired, snapshot_dates), data limitations (60-day TTL, snapshot gaps), and edge decay computation. No contradiction.

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

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

The description is well-structured, starting with the core question and then explaining the response fields and limitations. It is slightly verbose but efficient overall, with each part adding value.

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

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

Given the tool's complexity (telemetry over time) and the lack of an output schema, the description thoroughly explains the response structure (tracked[], expired[], snapshot_dates[]), includes data limitations (60-day TTL, gaps), and provides usage context. It is complete enough 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 description coverage is 100%, with both parameters (days, window) already described in the schema. The description mostly repeats this information (defaults, ranges) without adding significant new semantic meaning. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It answers the specific question 'how long has this edge existed and is it shrinking?' and distinguishes itself from sibling tools like polymarket_edges by focusing on time-series behavior rather than current edge values.

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

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

The description provides contextual guidance on when to use the tool, explaining the trade implication of old vs. new edges. While it doesn't explicitly state when not to use it or list alternatives, the context is sufficiently clear for an agent to decide.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds rich behavioral context: walking the ladder, return fields (top_of_book, vwap_fill_price, slippage, etc.), and the risk of partial basket fills converting arb into unhedged directional position. 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 verbose with multiple long paragraphs. While front-loaded with the purpose, it contains some redundancy and could be more concise. For example, the output details are repeated in both modes. A more structured format would improve conciseness.

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

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

No output schema exists, so the description must explain return values, which it does comprehensively for both modes, including verdicts, thin_legs, and forced directional risk. It also covers input constraints and usage advice. The agent has sufficient information to understand inputs and outputs without external documentation.

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

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

Schema coverage is 100% with parameter descriptions. The description adds further meaning: mutual exclusivity of market/event (not captured in schema), default values for side and size_usd, interpretation of size_usd for single vs basket, and auto-default for side in basket mode. This goes well 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 verb ('check') and resource ('realizable-vs-theoretical edge against live CLOB order-book depth'), and distinguishes between single-market and basket modes. It also differentiates from sibling tools by explicitly naming 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?

Explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500', with clear reasoning about thin books and directional risk. This provides both when-to-use and when-not-to-use context.

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

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

Annotations provide readOnlyHint, idempotentHint, openWorldHint. The description adds significant detail: safety fields (compatibility_warning conditions, temporal_alignment, skipped_cross_type/subtype), explains what the tool says when bet shapes are non-equivalent, and aligns with 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 well-structured with sections (modes, response, safety fields) and front-loaded with core purpose. It is slightly verbose (e.g., listing shortcuts again), but every part adds value. Conciseness is good but not perfect.

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 high schema coverage, no output schema, and sibling tools, the description is comprehensive. It explains output structure (leg-by-leg prices, top_spreads_pp), safety fields, and addresses potential misinterpretations (pre-mapped ≠ tradeable). No gaps.

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

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

Schema coverage is 100% and describes all parameters. The description adds value beyond schema by explaining the role of each parameter (e.g., topic overridden by explicit tickers) and providing examples. However, the schema already covers parameter meaning, so description adds moderate extra context.

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

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

The description clearly states the tool computes cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes two modes (topic shortcuts and explicit tickers) and is specific about its function, differentiating it from sibling tools like polymarket_arbitrage.

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

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

The description explicitly explains when to use each mode: topic for pre-mapped macros, explicit kalshi_event_ticker+polymarket_event_slug for custom pairings. It also warns that real spreads are rarer and most pre-mapped topics return compatibility_warning, providing clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds scoping detail ('Scoped to your identifier...') without contradicting annotations.

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

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

Three sentences, each purposeful and front-loaded with the core action. No redundant or unnecessary words.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description fully covers behavior, scoping, and relationship to sibling tools.

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

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

Schema coverage is 100% with a clear description for the 'key' parameter. Description clarifies behavior of omitting the key (list all), 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 specifies the verb 'retrieve' and 'list', the resource (saved values/keys), and distinguishes 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?

Describes when to use ('look up context the agent stored earlier') with concrete examples (ticker, address, research notes), but does not explicitly state when not to use or provide alternatives.

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

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

Annotations declare safe read-only behavior. Description adds important side-effect: mark_read flag affects next call's results. 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?

Two concise sentences packed with key information. Front-loaded with purpose. No filler or redundancy.

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

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

Adequately covers return fields, filtering, side effects, and alternative access. Missing explicit output format details, but no output schema exists.

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

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

Schema covers all 5 params (100%). Description adds context: 'ISO timestamp' for since, 'default 50' for limit implied, and explains mark_read consequences beyond schema.

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

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

Clear verb 'Pull' with specific resource 'fired events from your subscription feed'. States exactly what is returned (source, citation_uri, payload). Distinguishes itself from siblings by focusing on subscription feed alerts.

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

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

Explicitly mentions polling works fine and points to an alternative endpoint for scripts/dashboards. However, no direct comparison with sibling tools like 'subscribe' or 'recall'.

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

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

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description reveals fan-out to multiple APIs, fallback from GDELT to GNews, soft-failure for USPTO due to API sunset, and the parallel call nature. No contradictions with annotations.

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

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

The description is a single dense paragraph that front-loads with example queries, then succinctly covers sources, fallback, parameter formats, output structure, and sibling differentiation. Every sentence adds value without verbosity.

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 specifies the return format (structured changes[] grouped by source, total_changes count, citation URIs). It covers all aspects of the tool's behavior, including alternative use cases, making it complete for the given complexity.

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

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

Schema description coverage is 100%, but the description adds significant value: it explains that 'since' accepts ISO dates or relative shorthand ('7d', '30d', '3m', '1y'), gives examples, and recommends typical values. For 'value', it clarifies ticker or CIK formats.

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' and distinguishes it from the sibling tool 'entity_profile' which provides static profiles. It uses example queries to reinforce purpose.

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

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

The description explicitly advises when to use this tool vs 'entity_profile' for static profiles. It details the sources (SEC, GDELT, USPTO) and fallback behavior, and provides parameter recommendations (e.g., '30d' or '1m' for typical monitoring).

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 scoping by identifier and retention durations (24 hours for anonymous, persistent for authenticated). Annotations indicate idempotentHint=true and not readOnly, which aligns; 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?

Concise three sentences plus inline examples. Front-loaded with purpose, then usage, then behavior. No unnecessary words.

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

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

For a simple key-value store with no output schema, the description fully covers purpose, usage, persistence, and pairing with sibling tools. No gaps.

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

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

Schema covers both params with descriptions. Description adds examples of key and value formats, providing meaningful context beyond schema (e.g., 'subject_property', 'findings, addresses').

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 saves data for reuse later, with specific examples like 'resolved ticker', 'target address'. It distinguishes from siblings 'recall' and 'forget' by pairing them in the description.

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

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

Explicitly states when to use: 'when you discover something worth carrying forward'. Provides context on persistence (authenticated vs anonymous) and directs to pair with recall/forget.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that each call cascades through several endpoints internally, replacing 2-3 manual lookups, and details the return format for each type.

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 examples first, then details per type. Every sentence adds value, though it's slightly long 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?

For a lookup tool with no output schema, the description adequately explains return values (ticker, CIK, RxCUI, citation URIs) and behavior. It covers the complexity of multiple entity types and cascading lookups.

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

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

Schema coverage is 100% and description adds valuable examples (e.g., 'AAPL', 'ozempic') and explains that company accepts ticker, CIK, or name with auto-disambiguation, going beyond the schema.

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

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

The description clearly states it resolves names to canonical identifiers with specific examples like ticker, CIK, RxCUI. It distinguishes itself from siblings like entity_profile by emphasizing it's the first step when you have a name but need an ID.

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

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

Explicitly says 'Use FIRST whenever you have a name but need an ID.' Though it doesn't explicitly list when not to use, the guidance is strong and implies that if you already have an ID, this tool isn't needed.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, making safety clear. The description adds behavioral details: probes each entity, ranks by score, returns score/confidence/signal density, and internally calls ai_visibility_check. No contradictions; full transparency.

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

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

The description is three sentences: first states purpose, second describes process, third gives usage example and return format. Every sentence is essential and front-loaded. 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?

The tool has 4 parameters and no output schema. The description covers purpose, process, return value (ranked list with score/confidence/signal density), and usage context. It adequately informs the agent without needing to explain return values beyond what's stated. Could mention limits, but these are in schema (2-8 entities).

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: explains the 'entities' array treats first entry as 'subject', gives example for 'context' ('B2B SaaS'), and clarifies the 'models' parameter dependency with '_apiKey'. This goes beyond schema descriptions.

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

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

The description uses a specific verb ('Compare AI visibility'), identifies the resource ('multiple entities side-by-side'), and clarifies it probes with ai_visibility_check and ranks by score. It distinguishes from sibling tools like ai_visibility_check (single entity) and compare_entities (different comparison type).

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

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

The description provides clear usage context: 'Useful for competitive AI-marketing audits' with an example question. It implies when to use (comparing multiple brands) but does not explicitly state when not to use or list direct alternatives. Still, the guidance is sufficiently 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, etc. Description adds: composite call fanning out across two services, partial failures degrade gracefully, bundlephobia first measurement can take 5-30s, sources_failed field. 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?

The description is a single paragraph covering all necessary information, front-loaded with the main purpose. Though slightly long, each sentence adds value.

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

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

For a composite tool with multiple services, partial failures, and ecosystem restrictions, the description covers all critical aspects including return values (summary block, per-advisory detail, links, alternative versions) and failure behavior.

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

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

Schema description coverage is 100% for both parameters. The description mentions acceptance of scoped packages and defaulting version but does not add new semantics beyond what the schema already provides.

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

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

The description clearly states the tool as a composite check for npm packages covering license, advisories, version history, and bundle size. It distinguishes from siblings by specifying NPM ecosystem only in v1 and mentioning alternatives like deps.dev:version directly for other ecosystems.

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

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

Explicit usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also covers when not to use (other ecosystems) and partial failure behavior.

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

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

Annotations already indicate read-only and idempotent. Description adds that search is for US schools and gives return fields, which is helpful beyond annotations. No contradiction.

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

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

Two sentences and an example—minimal, front-loaded with key information, no extraneous 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?

Given output schema exists, description covers core purpose, parameters are well-documented in schema, and example reinforces usage. Complete for this tool's complexity.

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

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

All 4 parameters have schema descriptions (100% coverage). Description adds an example that demonstrates query and state usage, providing extra clarity.

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

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

Description clearly states it searches US colleges by name and lists specific return fields. The example further clarifies usage. Distinct from siblings like 'get_school'.

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 context on searching by name and a state filter example, but no explicit when-to-use or alternatives compared to sibling tools like 'get_school'.

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 underlying model (BGE-base-en), similarity metric (cosine), chunking (500-char overlapping windows), and character limit (200K chars with truncation and flagging). Annotations provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint false, and description adds these behavioral details without contradiction.

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

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

Three well-structured sentences: immediate purpose, usage scenario, technical details. Every sentence adds value, no fluff, front-loaded with key concept.

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 covers return types (top-N passages, character offsets, similarity scores) and flags truncation. Combined with high schema coverage and annotations, the description is fully informative for agent use.

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

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

Schema coverage is 100%, so baseline 3. Description adds examples for query ('supply-chain risk', 'drug interactions with warfarin'), clarifies text max (~200K chars), and limits for limit (1-20, default 5). These add meaning beyond schema definitions.

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

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

The description clearly states 'Semantic search INSIDE a fetched record' with concrete examples (SEC 10-K, article, long tool result). It distinguishes from sibling tools by mentioning pairing with ask_pipeworx_grounded for grounding over passages.

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

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

Explicitly says when to use: 'when the record is too big to cram into the prompt.' It explains benefits: saves context, returns only relevant passages with offsets. Implicitly differentiates from fetching whole documents, but lacks explicit when-not or alternatives.

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

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

The description provides extensive behavioral context beyond annotations: account requirement, always-on feed, optional channels with specific behaviors (webhook HMAC signing, auto-disable), and rate limits. Annotations only indicate idempotency and non-destructiveness.

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 front-loaded purpose and logical flow. It is relatively long but each sentence adds value, though webhook HMAC details might be considered verbose.

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

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

The description covers all key aspects: account requirement, supported types, params format, delivery options with constraints, and return value. Minor omissions like explicit error handling don't detract significantly.

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 meaningful context for each type and parameter (e.g., sec_8k items as officer change) and clarifies delivery fields beyond schema constraints.

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 creates a proactive monitoring subscription and returns a subscription ID. It distinguishes itself from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation of new subscriptions.

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

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

The description specifies prerequisites (Pipeworx OAuth account) and delivery channel limitations (SMS 10/day cap, webhook auto-disable). It does not explicitly name alternatives but context is clear given sibling tools.

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

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

Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true. The description adds that the tool returns example questions with exact tool+argument shape, which is useful context beyond the annotations. No contradictions.

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

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

The description is a single paragraph that front-loads the purpose with example queries. It is dense but well-structured. Could be slightly shorter, but it remains informative without redundancy.

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

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

Given the tool is a discovery tool with no output schema, the description adequately explains what it returns (category-bucketed example questions). It covers both modes of use and sets expectations for the output format. No missing critical information.

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

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

Schema coverage is 100% with the `topic` parameter described. The description adds value by explaining that omitting topic gives full spread and passing a specific topic focuses the results. This clarifies usage beyond the schema's description.

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

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

The description explicitly states the tool returns category-bucketed example questions with exact tool+argument shapes. The verb 'returns example questions' is specific and distinguishes it from sibling tools like ask_pipeworx (which answers actual queries) and discover_tools (which lists tools).

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

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

The description advises using this tool 'FIRST when you do not yet know what Pipeworx can do' and 'to learn how to call the meta-tools.' It explains both calling with no arguments for full spread and passing a topic to focus. It does not explicitly state when not to use it, 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?

Discloses that ownership is enforced and the row is deactivated (not deleted), which adds value beyond annotations that already mark destructiveHint as false. 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?

Two concise sentences, front-loaded with the primary action, and every sentence adds essential information without redundancy.

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

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

For a simple one-parameter tool with annotations and no output schema, the description covers purpose, constraints, and side effects adequately.

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

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

Schema coverage is 100% with a clear parameter description. The description reinforces that the id comes from subscribe, adding marginal value. Baseline 3 is appropriate.

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

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

Description explicitly states 'Cancel a subscription by id' with a specific verb and resource, clearly distinguishing it from siblings like subscribe and list_subscriptions.

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

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

Describes ownership enforcement and deactivation behavior, providing clear context for when to use. Could be more explicit about when not to use (e.g., for permanent deletion) but is adequate given simplicity.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds substantial behavioral detail: dual pipeline logic (structured SEC vs. grounded pipeline), exact percent-delta math, live source routing, verbatim evidence, and the verdict system. This transparency goes well beyond the annotations, fully equipping an agent to understand the tool's behavior.

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

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

The description is relatively long but front-loaded with example phrases and a clear purpose statement. Every sentence adds value, though slight trimming of examples might improve conciseness. Overall, it is well-structured and informative.

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

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

Given the tool's complexity (two verification paths, no output schema), the description is remarkably complete. It explains return values (verdict, grounded value with citation, reasoning) and covers both financial and general claim types. The context signals (100% schema coverage, no output schema) are fully addressed, leaving no critical 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?

The input schema has 100% description coverage, explaining both 'claim' and 'tolerance_pct' clearly. The description adds minor extra context (e.g., tolerance_pct default 'implied by wording, capped at 5') but does not fundamentally enhance understanding 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 explicitly states the tool's purpose: natural-language claim verification against authoritative sources. It provides concrete example query patterns and distinguishes the tool's unique approach (structured SEC path for financial claims, grounded pipeline for others) from generic fact-checking. Although sibling tools like ask_pipeworx_grounded exist, the description clearly carves out claim verification with verdict grading, making it unique.

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

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

The description says 'Use whenever the agent needs to check whether something a user said is factually correct,' providing clear context for when to use. It also notes that this tool replaces 4-6 sequential calls, implying efficiency. However, it does not explicitly state when not to use it or list alternative tools for edge cases, though the context is sufficient.

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