Gitlab

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing a strong safety baseline. The description adds relevant context about external calls: the default model is free (Workers AI Llama-3.3-70b), and passing _apiKey enables Anthropic probes with the user paying directly. This clarifies auth needs and the external nature of the calls 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?

The description is four sentences, each earning its place: purpose, model defaults/API key, return format, and use cases. It is front-loaded with the core function and contains no fluff 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?

Despite no output schema, the description explicitly lists the per-model return fields (score, confidence, signals, raw_response) plus a combined view, covering return values. It also explains model selection and use cases, making the tool fully comprehensible for an agent to decide when to invoke it and how to interpret results.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value beyond the schema by explaining the default model behavior when 'models' is omitted and the dependency between '_apiKey' and the 'anthropic' model option, which clarifies how parameters interact. This elevates it above the baseline.

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 function: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This is a specific verb+resource combination that distinguishes it from siblings like ask_pipeworx or deep_research, and the use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) further clarify its unique role.

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

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

The description provides clear context for when to use the tool ('Useful for AI-marketing audits, pre-launch brand checks, competitive monitoring'), but it does not explicitly mention when not to use it or name alternative tools. It also explains model selection (default vs. Anthropic with _apiKey), which is practical guidance, but lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context: it routes to sub-tools, fills arguments, returns structured data with stable citation URIs, works on every tier, and is a single fast call. This goes beyond annotations without contradicting them.

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

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

The description is long but front-loaded and well-organized, with a clear 'PREFER OVER WEB SEARCH' opening, domain list, examples, and escalation paths. Every sentence adds distinct value, though it could be slightly trimmed without losing meaning.

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 explains the return format ('structured answer with stable pipeworx:// citation URIs'), covers tier availability, gives examples, and clearly contrasts with sibling tools. For a single-question routing tool, this is thorough and 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 a clear description for 'question' and aliases. The description adds value by including concrete example questions ('current US unemployment rate', 'Apple's latest 10-K') that illustrate the expected natural language format, though it does not detail parameter syntax beyond what the schema provides.

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

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

The description immediately states 'PREFER OVER WEB SEARCH for questions about current or historical data' and enumerates specific domains (SEC filings, FDA drug data, etc.). It clearly explains the tool routes to 5,529 tools and returns structured answers with citations, distinguishing it from siblings like ask_pipeworx_grounded and deep_research.

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

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

Provides explicit when-to-use guidance: 'Use whenever the user asks...' with trigger phrases and examples. It also gives clear alternatives: 'Step up only when needed' for ask_pipeworx_grounded and deep_research, and notes when not to use it (breaking news is handled internally).

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

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

The description discloses key behavioral traits beyond annotations: it is a full working router with no fallback, candidate routing improvements are enabled live when under test, and no candidate is active currently so it matches ask_pipeworx exactly. This complements the readOnlyHint and idempotentHint annotations with valuable context about the beta status.

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 roughly five sentences, longer than the minimal, but every sentence adds relevant information about the beta status, current state, usage guidance, and experimental nature. It is front-loaded with the most important fact ('Beta version of ask_pipeworx') and remains focused.

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

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

It covers the beta relationship, usage instructions, safety profile via annotations, and the fact that it has the same response shape as ask_pipeworx. It doesn't mention output schema (none exists) but references the sibling for shape, which is sufficient for an agent aware of ask_pipeworx.

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

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

The input schema already documents all six parameters with 100% coverage, including descriptions for 'question' and its five aliases. The tool description adds no parameter-specific details, so per the baseline rule a score of 3 is appropriate.

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

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

The description clearly states this is the beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by the 'beta' label and the mention of candidate routing improvements, leaving no ambiguity about its 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?

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router to decide merges. This provides a clear usage scenario and implicitly defines ask_pipeworx as the stable alternative, satisfying the when-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?

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses the grounded extraction process, exact refusal reasons (not_in_source, no_tool_match, etc.), and the extra LLM call cost. It also details the success and failure return structures, adding substantial behavioral context not covered by 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 front-loaded with the core value proposition and follows a logical sequence: purpose, mechanism, return format, usage, and cost tradeoff. Every sentence earns its place, with no redundancy or filler, making it efficiently structured for its complexity.

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

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

Without an output schema, the description fully specifies the success and refusal return structures, including keys and refusal_reason values. It also covers high-stakes use cases, cost implications, and the relationship to ask_pipeworx, providing a complete picture for an agent to invoke the tool correctly.

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

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

The schema covers all 6 parameters with 100% description coverage, though the descriptions are minimal ('Alias for question'). The tool description does not add parameter-level details beyond the natural language question concept. Since coverage is high, a baseline of 3 is appropriate; no additional meaning is provided.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads,' clearly stating a specific verb and resource. It further distinguishes from the sibling tool ask_pipeworx by explaining the grounded extraction mechanism and explicit refusal behavior, making the purpose unmistakable.

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

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

The description provides explicit usage guidance: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and names the alternative 'prefer ask_pipeworx for casual lookups.' This clearly delineates when to use this tool vs. its sibling.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses rich behavioral traits: parallel fan-out, blocking low-confidence/closed-market paths, wide-spread tradeability warnings, news fallback fields, and resolution-rule risk parsing. It explains exactly what happens with fuzzy matches and how safety short-circuits work, adding substantial value beyond the structured data.

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 labeled sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loads the purpose. However, it is very long and dense, with some redundancy (e.g., repeated low-confidence match details) that could be trimmed without losing value. Still, given the tool's complexity, the length is largely justified.

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?

Without an output schema, the description must explain return values, and it does so exhaustively: response shapes, resolver contract fields, parent_event extractor, news fields, safety statuses, and cancellation rules. It covers edge cases like closed markets, illiquid spreads, and fuzzy matches, making the description complete for an agent to invoke the tool correctly.

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

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

The schema description coverage is 100%, and each parameter (market, depth, include_raw) already has detailed descriptions in the schema. The tool description adds some context via examples and fan-out behavior but does not materially enhance parameter meaning beyond what the schema provides, so the 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 opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes the tool's scope (single-bet research) from sibling Polymarket tools like polymarket_edges or polymarket_arbitrage, and states the input formats and high-level behavior.

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

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

The description gives explicit 'Use for' scenarios: 'should I bet on X', 'what does the data say about Y', or 'is there edge in Z'. It also provides many fan-out examples showing when each category applies. However, it does not explicitly name alternative tools or state when not to use this tool, only implying it through the use cases.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS/FDA), handling of off-calendar fiscal years, sorting by primary metric, and the return format (paired data with citation URIs). 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 information-dense but every sentence earns its place: query patterns, data sources, fiscal-year edge cases, sort behavior, return format, and efficiency claim. It is front-loaded with the main purpose and remains readable.

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

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

Given the tool's complexity, no output schema, and two distinct entity types, the description fully explains what the agent can expect: paired data, citation URIs, and sorted results. It also covers edge cases like off-calendar fiscal years and explicitly states the number of lookups replaced.

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

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

Schema already covers the two parameters, but the description adds substantial meaning: exactly what data each 'type' value retrieves, the expected format for values (tickers/CIKs for company, drug names for drug), and the cardinality (2–5). This goes well beyond the bare schema.

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

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

The description opens with query examples and then states the core function: side-by-side comparison of 2–5 companies or drugs in ONE parallel call. It clearly distinguishes from sequential lookups by explicitly preferring itself for comparisons and noting it replaces 8–15 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?

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing an unambiguous when-to-use rule and an implied alternative. It also separates usage by entity type (company vs drug) with data source specifics.

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

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

The description adds extensive behavioral detail beyond the annotations: account requirement, paid plan for thorough depth, output packet structure with gaps[] and contradictions[], citation_uri resolvability, semantic excerpting, latency expectations, and limitations with news topics. It also explains the second-hop iteration and 'never invented' aspect, which the annotations do not cover.

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

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

The description is long but dense with essential operational details (account, alternatives, depth semantics, output structure, latency). It front-loads the core purpose and exclusions, but the single-paragraph format is hard to scan and a few phrases are redundant (e.g., 'so a citation you get back is always fetchable'). For a complex tool, the length is largely justified.

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

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

Despite having no output schema, the description comprehensively covers the tool's execution model, output fields, gap/contradiction behaviors, depth modes, account/preconditions, latency, alternatives, and failure modes for news topics. The agent has enough context to select and invoke this tool correctly, including fallback to ask_pipeworx when appropriate.

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

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

The input schema already provides 100% parameter coverage, including a detailed description of each depth level. The description adds only the paid-plan requirement for 'thorough' and reinforces gap-recovery behavior already in the schema, which is marginal added value. The baseline of 3 is appropriate given the high schema coverage.

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

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

Clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call, with explicit examples and a strong contrast to open-web search. It distinguishes itself from the sibling tool ask_pipeworx by noting it is best for broad/multi-part questions while ask_pipeworx handles single lookups.

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

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

Provides explicit usage guidance: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS ... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. This fully covers when to use and when to choose alternatives, naming the exact sibling 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 and idempotentHint=true, so safety is covered. The description adds valuable behavioral context about the return: 'top-N most relevant tools with names, descriptions, and full input schemas (with curated examples)' and 'each result is ready to call directly, no second schema lookup needed.' This goes beyond the annotations and helps set expectations for output format and callability, though it doesn't cover error cases or rate limits.

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

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

The description is three sentences, front-loaded with the core purpose, and each sentence serves a function: purpose, domain list, and return behavior. The domain list is somewhat long but adds helpful specificity. Overall it is efficient without being terse, earning a 4 rather than 5 due to slight 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?

There is no output schema, so the description appropriately explains the return value: top-N tools with names, descriptions, schemas, and curated examples, ready to call. This covers what the agent needs to know for invocation and follow-up. The description is complete for a discovery tool with strong annotations and full parameter schema coverage.

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

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

Schema description coverage is 100%, so the schema already describes all six parameters including aliases and the limit field. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate. It mentions 'top-N' and 'limit' indirectly but the schema already covers the limit's default and max.

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

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

The description opens with a clear verb+resource: 'Find tools by describing the data or task.' It lists concrete domains (SEC filings, FDA drugs, FRED economic data, etc.) and distinguishes itself from sibling tools by being a meta-tool for discovery, not a task-specific tool. This is a specific, non-tautological 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 says 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear when-to-use guidance and implies a contrast with sibling tools that provide direct answers, without needing to name them.

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 the tool read-only and idempotent, and the description adds substantial behavioral context beyond that: fan-out across sources, specific return fields (cik, filings with URIs, fundamentals sorted by period_end, patents with sunset warning, news fallback GDELT→GNews, LEI), and the 'up to 5' limit. It also discloses the inability to accept names, preventing misuse.

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?

Though long, the description is densely packed with useful information and never wastes a word. It opens with example queries, then the core purpose, then usage priority, then a structured list of return items, then input format. Each segment earns its place, and the semicolon-delimited return list is easy to scan.

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

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

The tool is complex (fan-out over multiple APIs, multiple return fields, fallbacks, limits) and there is no output schema, but the description fully enumerates the return fields, data sources, sort order, limits, and fallback behavior. Nothing essential is missing.

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

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

Schema coverage is 100% and the schema already describes both parameters thoroughly, including the ticker/CIK format and the name-not-supported caveat. The description echoes the schema without adding new parameter-level semantics, so the baseline of 3 applies.

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 is extremely clear about what the tool does: it builds a full cross-source profile of a US public company in one parallel call. It provides multiple natural-language example queries and explicitly names the resources (SEC EDGAR, XBRL, USPTO, news, GLEIF). It also differentiates from siblings by stating 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-only inputs.

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

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

The description gives explicit when-to-use guidance ('when the user asks for a holistic view'), names the alternative (resolve_entity first if only a name), and notes the patents API soft-fail behavior. This is a model of clear usage instructions.

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 destructive and idempotent behavior. The description adds that it targets 'previously stored memory,' clarifying the scope of deletion. This is useful context without contradicting the annotations.

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

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

Two concise sentences with the action front-loaded. The first sentence states the operation; the second provides usage scenarios and sibling relationship. 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 one-parameter tool with strong annotations and complete schema, the description effectively covers purpose, usage, and related tools. It omits edge-case behavior like missing keys, but that is minor for this tool.

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

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

Schema coverage is 100% and the parameter 'key' is described as 'Memory key to delete.' The description's 'by key' essentially restates this, adding minimal extra meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Delete a previously stored memory by key.' It clearly distinguishes the tool from siblings by naming 'remember and recall' and framing this as the opposite operation.

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

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

It explicitly lists when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also points to related tools ('Pair with remember and recall'), giving clear contextual guidance.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable context beyond this: it 'fetches the page,' 'extracts title/description/key links,' and emits 'a single text blob ready to drop at site-root/llms.txt.' This explains the network fetch and output format without contradicting the annotations.

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

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

The description is three sentences, front-loaded with the main purpose, then a brief process explanation, then use cases. Every sentence earns its place with no fluff or repetition of schema fields. It is concise, well-structured, and easy to scan.

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 2-parameter tool with no output schema, the description is complete: it explains what the tool does, how it works, what the output looks like, and when to use it. The annotations cover safety (read-only, non-destructive), and the output is described as a single text blob ready to drop at site-root/llms.txt. No significant gaps remain.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the schema already documents them fully. The description adds minimal parameter-specific meaning (e.g., 'any URL' implies broad url usage) but does not elaborate on max_links or its default. Baseline 3 is appropriate given the schema covers the parameters.

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

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

The description clearly states the tool generates a production-ready llms.txt file for any URL, with a specific verb ('Generate'), a clear resource ('llms.txt file'), and a defined scope ('for any URL'). It also explains the process (fetches page, extracts title/description/key links) and output format, distinguishing it from any sibling tool in the provided list.

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

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

The description explicitly lists three use cases: getting a client's site indexed by AI, drafting llms.txt for your own project, and auditing how an AI crawler would see a competitor. This gives clear context for when to use the tool, though it does not explicitly name alternatives or state exclusions, which would merit a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds return payload details (decoded content, file size, name, encoding), which is helpful, but it does not disclose operational edge cases like binary file handling or error 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 a single, front-loaded sentence with an inline example ('src/main.py'). It conveys the purpose, input, and return values with no wasted words.

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

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

Given the tool's low complexity, rich annotations, 100% schema coverage, and the presence of an output schema, the description is complete. It mentions the input mechanism, the example path, and the return contents, which is sufficient for an agent to select and invoke the tool correctly.

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

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

The input schema provides descriptions for all 4 parameters, giving 100% schema description coverage. The description reinforces file_path via an example and mentions project_id, but it does not add semantic meaning beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description uses the specific verb 'Fetch' and names the resource 'file content from a GitLab repository', along with the key inputs (project ID and file path). This clearly distinguishes it from sibling tools like gitlab_get_project, gitlab_list_issues, and gitlab_list_mrs.

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

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

The description states the tool's purpose—fetching file contents—which makes the use case clear. It does not explicitly mention alternatives or when-not to use it, but the context is unambiguous and no exclusions are 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, and destructiveHint=false, so the tool's safety is clear. The description adds no additional behavioral context such as rate limits, auth specifics, or side effects. It provides return field examples, but with an output schema, this is redundant.

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 that concisely states the purpose and key input flexibility. It is front-loaded with the action and resource, and every phrase adds value. 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 strong annotations, complete schema, and an output schema for return values, the description covers the essential need-to-know information. However, it does not mention failure conditions or explicitly guide tool selection among GitLab siblings, which would improve 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?

Both parameters are fully described in the schema (100% coverage), including examples and encoding requirements. The description reiterates the id format but adds no new semantic information. Therefore it meets the baseline for high schema coverage.

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

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

The description clearly states the action ('Get') and resource ('details for a specific GitLab project'), with explicit input formats (ID or path). It distinguishes itself from sibling tools like gitlab_list_projects and gitlab_get_file by focusing on a single project's 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 conveys a clear use case: retrieving details of one specific project. It does not explicitly name alternatives or exclusions, but the phrase 'specific' implies contrast with listing tools. Since sibling names are available, the agent can infer when to use this tool, but explicit guidance is missing.

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

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

The description adds the return fields, which is useful. However, it falsely claims 'Filter by status and labels' while the schema has a 'state' parameter and no 'labels' parameter. This misleading claim contradicts the schema and could cause the agent to pass an invalid 'labels' argument. Annotations already cover read-only and idempotent traits, so the description's misleading filter is a significant transparency issue.

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

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

Two sentences, front-loaded with purpose and return fields. The structure is efficient and easy to parse, though the content includes the 'labels' inaccuracy. The compactness is good.

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 an output schema and strong annotations, the description doesn't need to explain return formats. It is adequate for a simple list tool, but the erroneous 'labels' filter and use of 'status' instead of 'state' create a gap in completeness, leaving the agent uncertain about actual filter options.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal semantic value beyond the schema: it mentions 'project ID' (already required) and repeats filter capabilities, though 'labels' is not a schema parameter. No additional parameter nuances are provided.

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 searches issues in a GitLab project by project ID and lists the returned fields (ID, title, state, labels, assignee, URL). This distinguishes it from sibling tools like gitlab_list_mrs (merge requests) and gitlab_get_project.

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

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

It provides clear context: search issues by project ID and filter by status/labels. However, it does not explicitly mention when not to use it or name alternatives, though the context is sufficient for an agent to select this tool for issue listing.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the tool requires a project ID and returns specific fields, but return fields are also in the output schema, so this adds limited value. No hidden behaviors are disclosed, but annotations carry the burden.

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 only two sentences and front-loads the core purpose, which is structurally concise. However, the inaccuracy about filtering by author means the second sentence does not fully earn its place. A concise, accurate description would score higher.

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, full schema coverage, and output schema existence, the description is mostly adequate. The author filter claim introduces ambiguity and the default state (opened) is not mentioned, though it is in the schema. The description is not fully complete due to the inaccuracy.

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

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

Schema coverage is 100%, so the baseline is 3. However, the description claims 'Filter by state and author', but the schema does not include an 'author' parameter. This is misleading and could cause an agent to pass an unsupported parameter. The error in the description outweighs the schema's completeness, so a lower score is warranted.

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 ('List') and identifies the exact resource ('merge requests in a GitLab project by project ID'). It clearly differentiates from sibling tools like gitlab_list_issues and gitlab_list_projects by specifying merge requests and the project scoping. The return fields are also listed, aiding purpose clarity.

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

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

The description provides clear context: use this tool to list merge requests for a given project ID. It does not explicitly mention alternatives or exclusions, but the sibling tools are for different resources (files, projects, issues), so the intended usage is unambiguous. A slightly higher score would require explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds value by listing the return fields (ID, name, path, description, star count, URL), giving the agent an expectation of the response shape beyond annotations.

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

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

The description is two sentences long, front-loaded with the main purpose, includes return details, and directly points to the alternative tool. Every sentence is useful and there is zero redundancy.

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

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

The tool is simple and the description covers its core purpose, return values, and relationship to a sibling. An output schema exists, so detailed return types are not needed in the description. However, it could mention pagination behavior or that 'all accessible' might imply a long list, but the schema's per_page parameter handles that.

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 with all four parameters clearly documented. The description adds no additional parameter-level meaning beyond what the schema already provides, so the 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 'List all accessible GitLab projects' which is a specific verb+resource combo. It also distinguishes from the sibling tool gitlab_get_project by noting that detailed info is available there, making it easy to identify this as the listing 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?

The description explicitly names an alternative: 'Use gitlab_get_project to fetch detailed info.' This provides clear guidance on when to use this tool vs. a close sibling, though it does not mention exclusions for other siblings like gitlab_list_issues or gitlab_list_mrs.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns by using 'List'. It adds behavioral detail by enumerating the returned fields (id, type, params, created_at, last_fired_at, fire_count) and scoping it to 'active subscriptions', which is valuable beyond the annotations.

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

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

The description is two sentences, front-loaded with purpose and return fields, followed by practical usage guidance. Every sentence adds value with no redundancy.

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

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

Given the tool's simplicity, the description fully covers necessary context: what it does, what it returns, when to use it, and the safety profile is covered by annotations. No output schema exists, but the description lists return fields, so it 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?

The input schema covers the single parameter (include_inactive) with a clear description and default. The main description does not add additional parameter semantics, and schema coverage is 100%, so a baseline 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, naming the specific resource and action. It also distinguishes itself from sibling tools like subscribe and unsubscribe by framing it as a review action.

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 context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This indicates when to use the tool, but it does not explicitly name alternatives or provide when-not-to-use guidance, so it stops short of a perfect score.

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?

With all annotations false (no readOnly, idempotent, etc.), the description carries the full burden and fully delivers. It discloses the claim_token flow, state that it is 'Rate-limited to 5 per identifier per day,' and clarifies it is 'Free; doesn't count against your tool-call quota.' It also reveals that the team reads digests daily.

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

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

The description is long but every sentence serves a distinct purpose: purpose, when-to-use, exclusions, message guidance, claim_token, rate limit, and cost. It front-loads the primary purpose but is more verbose than the two-sentence ideal; still, no content is wasted.

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, and the tool has nested objects and two distinct operation modes (submit feedback and check status). The description explains both modes, the optional context object, the claim_token flow, rate limits, and what happens after filing. 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 coverage is 100%, so the baseline is 3. The description adds meaning by advising message formatting: 'Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt.' It also clarifies claim_token usage beyond the schema by describing the dual-mode behavior (submit vs. read reply).

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes the tool from siblings by being the dedicated feedback channel, with enumerated feedback types (bug, feature/data_gap, praise).

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides an explicit when-not-to-use and alternative: 'if the tool came from a different MCP server... file it with that server instead.'

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds rich behavioral context: it is self-aggregating, derived from CF analytics-engine, contains no PII, and is cached 5min-1h depending on window. This informs the agent about data freshness and privacy, exceeding what annotations alone provide.

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

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

The description is front-loaded with the main purpose, followed by a concise list of use cases and a brief technical note. It is slightly longer than strictly necessary but every sentence adds value. The structure is logical and easy to scan, though the use-case list could be tightened.

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

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

Given the tool's simplicity (one optional parameter, no output schema), the description is complete: it explains what is returned, the available windows, caching behavior, and data privacy. There is no missing information that an agent would need to decide whether and how to call this tool.

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

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

The only parameter 'window' has full schema coverage with its enum and basic description. The tool description adds extra semantic value by explaining that shorter windows surface what's hot right now while longer windows show steady-state demand, which helps the agent choose appropriately. This goes beyond the schema's simple enum listing.

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

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

The description clearly states what the tool does: it returns the top tools, top packs, and total call volume over a recent window. The verb 'Returns' is specific, and the resource is well-defined. It also distinguishes itself from siblings like discover_tools by focusing on what other AI agents are calling on Pipeworx, 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 provides explicit use cases: discovering hot data sources, confirming canonical tool choices, and checking alignment with agent behavior. It also explains how to choose the window parameter based on needs (shorter for hot right now, longer for steady-state demand), offering clear guidance on when to use this tool.

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

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

Annotations already declare readOnly/openWorld/idempotent, but the description adds significant behavioral detail: fill-check logic with realizable edge ≤ 0, Jaccard similarity threshold, placeholder filtering rules, and the null-signal behavior for partitions with >20% placeholders. These go well beyond structured fields.

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?

Although lengthy, the description is front-loaded with the core purpose and structured with clear labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK). Every sentence adds unique information and the examples are relevant, making it dense but not wasteful.

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

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

Given the tool's complexity and lack of output schema, the description thoroughly covers all three modes, response shapes (opportunities[], partition_check{}), edge cases (placeholder filters, low similarity), and the fill-check pipeline. It is self-sufficient for correct invocation.

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

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

Schema coverage is 100%, but the description enriches both `event` and `topic` with behavioral outcomes, examples, and internal thresholds like Jaccard ≥ 0.30, 3pp deviation, and 20% placeholder exception. This provides substantial meaning 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 identifies the tool as an arbitrage finder on Polymarket using monotonicity violations and partition-sum checks. It distinguishes from siblings by detailing three specific modes (trending_scan, event, topic) and explicitly referencing polymarket_fill_risk for custom sizing.

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

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

Provides explicit when-to-use guidance: no args for trending scan, `event` for a specific market, `topic` for cross-event scanning. Includes concrete examples for each mode and names polymarket_fill_risk as the alternative for custom sizing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and the description goes far beyond by detailing caching behavior, output structure, internal gates, and warning about market moves. It even exposes diagnostics and the reasoning behind gate relaxations, which is exceptionally transparent.

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

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

The description is an extremely long, dense paragraph with no section breaks or bullet points, making it hard to scan. Although most details are relevant, the lack of structure and excessive length hurts readability and information retrieval.

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

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

Given the absence of an output schema, the description thoroughly covers the response structure (by_segment, fed_candidates, _diagnostics) and the fields carried by each opportunity. It also covers behavioral aspects like caching and edge cases, making it fully complete for an agent to understand the tool's behavior.

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

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

The schema provides 100% coverage with detailed descriptions for all 9 parameters, so the description need not repeat them. The description does add some context about how knobs like min_liquidity and max_spread_pp interact with tradeability, but this is largely redundant with the schema's own explanations.

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

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

The description clearly identifies the tool's purpose: scanning Polymarket markets and returning opportunities where Pipeworx data disagrees with market price. It distinguishes from siblings like polymarket_arbitrage by focusing on model-driven edge detection rather than pure 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 states it's built for 'what should I bet on today' and notes that it returns opportunities without paging hundreds of markets, providing a clear use case. It also mentions limitations like Fed bets being excluded due to unreliable signals, but it does not explicitly name alternative tools for when not to use it.

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

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

The description extensively discloses behaviors beyond the annotations: snapshots are daily and written on cache-miss, history depth is bounded by a 60-day TTL, decay is computed from daily closes rather than intraday, and response includes expired opportunities with lifespans. This adds rich context that the readOnly/openWorld/idempotent annotations do not provide.

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

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

The description is long but extremely dense, organized with labeled sections (Args, RESPONSE, LIMITS) that enhance scannability. Every sentence contributes meaningful information about behavior, output format, or limitations, with no filler.

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

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

Despite lacking an output schema, the description fully specifies the response structure (tracked, expired, snapshot_dates), explains edge cases like missing snapshot days, and details computation limitations. This is complete for a read-only telemetry tool, providing all necessary context for invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining 'window' as a snapshot family and how 'days' and 'window' affect the returned time-series, including the response details that clarify their impact. This goes slightly beyond the schema's parameter descriptions.

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

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

The description clearly identifies the tool as providing 'Edge persistence and decay telemetry' built from daily snapshots, answering a specific question about edge longevity and shrinkage. This distinguishes it from sibling tools like polymarket_edges which likely focus on current edges, by emphasizing the time-series perspective.

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

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

The description implies when to use the tool by contrasting fresh vs old edges and noting that 'the median lifespan is your competition clock', offering clear context for adoption. However, it does not explicitly name alternative tools or state exclusions, so it misses the full 'when not to use' guidance.

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

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

Annotations already declare readOnly, non-destructive, idempotent, and open-world behavior. The description adds substantial behavioral context: it walks the order-book ladder, returns specific verdicts and fields, explains size_usd interpretation (max spend vs target proceeds vs settlement notional), and names risk factors like forced_directional_risk. No contradiction with annotations.

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

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

The description is long but every sentence serves a purpose. It is front-loaded with the core purpose, then organized into clearly labeled SINGLE-MARKET and BASKET sections. Despite density, the structure aids scanning, and there is no wasted text or repetition of schema 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?

This is a complex tool with two modes and no output schema, yet the description enumerates the full set of return fields for both modes, explains parameter defaults and clamps, and warns about the primary risk (partial fills stranding unhedged positions). It is complete enough for an agent to invoke correctly 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?

Though the schema covers 100% of parameter descriptions, the tool description enriches meaning significantly. It explains how `market` vs `event` selects single-market vs basket mode, how `side` semantics differ between modes, and how `size_usd` is interpreted differently ('max spend on buys, target proceeds on sells' for single-market; 'settlement notional S' for basket). 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 opens with a clear, specific verb phrase 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and immediately distinguishes the two operating modes. It also names sibling tools (polymarket_arbitrage, polymarket_edges) as the context where this tool should be used, differentiating it from those alternatives.

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

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

The description provides explicit usage guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It explains why by describing the failure mode of partial basket fills converting an arb into unhedged directional risk, making the when-to-use decision 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, and openWorldHint, but the description goes far beyond by detailing safety fields: compatibility_warning conditions, temporal_alignment with aligned:false meaning spreads are mathematically meaningless, and skipped_cross_type/subtype counters that explain dropped comparisons. This provides substantial behavioral context beyond the annotations.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS). Every paragraph adds substantive detail about edge cases and response semantics; there is no filler. However, the length is considerable, so it sacrifices brevity for completeness, keeping it from a perfect score.

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

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

With no output schema, the description fully documents the response: leg-by-leg prices, spread format, compatibility_warning logic, temporal alignment, and counters. It covers all three parameters, both modes, and critical caveats. Given the tool's complexity and the absence of an output schema, this description is exceptionally 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%, but the description adds crucial semantics: it explains that 'topic' auto-fetches matching events, and that kalshi_event_ticker/polymarket_event_slug 'override the topic-mapped side.' It also enumerates the exact topic shortcuts and gives example ticker/slug values. This enriches the schema descriptions meaningfully.

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

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

The description opens with an explicit statement: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the two venues, the comparison (spread), and the condition (same question), clearly distinguishing it from sibling tools like polymarket_arbitrage. The two modes (topic shortcuts vs explicit ticker/slug) further clarify the tool's scope.

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

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

The description clearly explains when to use topic mode vs explicit mode and warns that pre-mapped shortcuts often return compatibility_warning, signaling that real spreads require explicit pairing. It does not explicitly name alternative tools, so it misses the opportunity to differentiate from siblings, but within its own context it provides solid usage guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the description is not burdened with stating these. It adds valuable behavioral context about scoping ('Scoped to your identifier') and the optional list-all-keys behavior, which goes beyond what annotations convey. However, it does not disclose return format or potential errors, but this is minor for a read-only lookup.

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, front-loaded with the core function. Every sentence adds value: the first states the action, the second gives usage rationale and examples, and the third provides scoping and pairing with related tools. There is 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 optional parameter and no output schema, the description covers purpose, usage, scoping, and relationships with sibling tools. Annotations handle safety semantics, and the description provides enough behavioral context for an agent to select and invoke the tool appropriately.

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

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

Schema coverage is 100%, so the baseline is 3. The description enhances parameter meaning by providing realistic examples of 'key' values and restating the omit-to-list behavior, which reinforces the schema. It also adds context about scoping that clarifies how keys are stored, giving more semantic depth than the schema alone.

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

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

The description uses specific verbs 'Retrieve' and 'list' with a clear resource ('a value previously saved via remember' and 'all saved keys'). It distinguishes the tool from siblings by explicitly naming related tools 'remember' and 'forget', making its role in the memory workflow unambiguous.

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier' and provides concrete examples (target ticker, address, research notes). It also implies the alternative of re-deriving information ('without re-deriving it from scratch') and pairs with 'remember' and 'forget', giving 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?

Beyond the annotations (readOnlyHint, openWorldHint, etc.), the description discloses that mark_read mutates read state, the feed is persisted, and the same data is available via a URL. This adds significant context about side effects and external access.

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 the core purpose, and each sentence earns its place by adding return details, filtering options, side effects, or alternative access. No waste.

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

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

Given no output schema, the description covers return fields (source, citation_uri, payload), filtering, side effects, and alternate access. With all parameters already described in the schema, this is a complete and self-sufficient description for an agent.

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

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

Schema coverage is 100%, so parameters are already documented. The description enhances this with a concrete type example ('sec_8k'), explains ISO timestamps for since, and clarifies the effect of mark_read, adding meaning beyond the schema.

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

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

The description uses a specific verb ('Pull') and clearly identifies the resource ('fired events from your subscription feed'). It distinguishes from sibling tools like list_subscriptions by focusing on event alerts, not subscription management.

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

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

Provides clear usage guidance: explains filtering by type and since, describes mark_read behavior, and notes polling is fine. However, it does not explicitly compare to alternative MCP tools or state when not to use it.

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

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

Beyond the readOnly/idempotent annotations, it discloses the fan-out to SEC EDGAR, GDELT→GNews fallback on rate limits/5xx, USPTO soft-fail due to PatentsView sunset, and the output citation URIs. This is rich behavioral context.

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

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

The description is dense but each clause adds needed detail about sources, fallbacks, date formats, and output shape. It's slightly long but not padded; the information justifies the 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 no output schema, the description adequately covers return structure (grouped changes, total_changes, citation URIs) and all required parameters. It also explains failure modes and alternative tool usage, making it operationally 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%, so the baseline is 3. The description adds value by giving concrete examples for 'since' (ISO or relative shorthand) and recommending '30d'/'1m', plus examples for 'value' (ticker vs CIK). 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 clearly states the tool returns a change feed for a company over a time window, covering filings, news, and patents. It also explicitly distinguishes itself from entity_profile, making its purpose and scope unmistakable.

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

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

It provides explicit usage triggers (e.g., 'What's new with X', 'updates on Acme') and directs users to entity_profile for static profile needs. It also explains fallback behavior and date formats, giving clear when-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?

The annotations already indicate this is a write operation (readOnly=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds valuable context about scoping by user identifier and persistence duration (authenticated vs 24-hour anonymous sessions), going beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core purpose. It covers purpose, usage, storage mechanics, and companion tools without waste. Slightly verbose in the usage examples but still efficient.

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

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

For a simple two-parameter tool with comprehensive schema, annotations, and no output schema, the description fully covers necessary context: when to use, persistence behavior, scoping, and integration with recall/forget. There are no meaningful 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 description coverage is 100% for both parameters, so the schema already carries the param semantics. The description adds only contextual examples of keys and value types, which is nice but not essential beyond what the 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?

The description clearly states the tool's purpose with a specific verb ('Save') and resource (data for later reuse). It explicitly distinguishes the tool from siblings by mentioning key-value storage and pairing with recall/forget, leaving no ambiguity.

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

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

Provides explicit when-to-use guidance with concrete examples (resolved ticker, target address, user preference, research subject) and names related tools (recall, forget) for retrieval and deletion. This clearly differentiates from 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 mark it read-only, idempotent, and non-destructive. The description adds valuable behavioral context: explicit labeling of unresolved identifiers, graceful degradation when GLEIF/OpenFIGI are unavailable, and cascading internal lookups. This goes well beyond the annotations and provides a robust model of tool 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 detailed but well-organized: opening examples, purpose, usage instruction, then supported types with output specifics. It is front-loaded and every section serves a purpose, though slightly verbose with the example list. Overall, it is concise enough for the tool's complexity.

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

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

Despite lacking an output schema, the description thoroughly covers return values for both entity types, including identifier sources, unresolved handling, degradation behavior, and internal cascading. This is highly complete for a 2-parameter tool with good annotations.

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 parameters are already well-documented. The description reiterates accepted input formats (ticker, CIK, name; brand/generic) and adds examples, but it does not add meaningfully beyond the schema descriptions. Thus, the baseline of 3 is appropriate.

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

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

The description clearly states the tool resolves user-spoken names to canonical/official identifiers, with a specific verb ('resolve') and resource ('name to identifiers'). It includes concrete example queries ('What's the ticker for...', 'find the CIK for...') and positions itself as a prerequisite for other tools, distinguishing it from siblings like entity_profile.

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

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

The description explicitly instructs 'Use FIRST whenever you have a name but need an ID,' giving clear when-to-use guidance. It also notes that the tool replaces 2-3 manual lookups. However, it does not explicitly state when not to use it or name alternative tools, so it lacks full exclusion/alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds that it internally calls ai_visibility_check, ranks by score, and returns score, confidence, and signal density per entity—beyond what annotations convey. 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?

Three sentences, front-loaded with the core purpose, followed by mechanism and use case. Each sentence earns its place: purpose, process, and outcome. No fluff 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?

No output schema exists, but the description explicitly states the return format (ranked list with score, confidence, signal density per entity). It also covers the internal probe step and gives a concrete use case. Given the tool's moderate complexity and annotations, this is sufficiently 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%, so all parameters are described. The description does not add much beyond schema; it rephrases the 'entities' semantics (first entry as subject, rest competitors) which is already in the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('Compare'), resource ('AI visibility across multiple entities'), and scope ('side-by-side'), distinguishing it from the sibling ai_visibility_check which checks a single entity. It also explains the mechanics: probes each entity, ranks by score, and surfaces most/least recognized.

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

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

The description provides a clear use case ('competitive AI-marketing audits') with an illustrative question, and implies it is for multi-entity comparison. It does not explicitly name alternatives or state when not to use it, but the context is sufficient for an agent to judge applicability.

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 substantial behavioral context beyond these: it is a composite tool that fans out to two services, it handles partial failures gracefully, bundlephobia's first measurement can take 5-30s, and sources_failed will report timeouts. It also details what the return payload includes. This adds significant value beyond the structured annotations.

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

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

The description is dense but every sentence earns its place. It front-loads the core purpose, then lists the data sources, usage triggers, output structure, ecosystem limitation, and failure behavior. There is no redundant content, and the structure is logical. The length is justified by the complexity of a composite tool.

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

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

The tool has no output schema, so the description carries the full burden of explaining what is returned. It explicitly lists the summary block fields, per-advisory detail, links, and alternative versions. It also covers timing risks, partial failures, and ecosystem scope. Given the tool's complexity, this description is complete and sufficient for an agent to invoke it 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%: both `package` and `version` have clear descriptions in the input schema. The tool description doesn't add any additional parameter semantics beyond what the schema already documents, so the baseline of 3 is appropriate. It doesn't hinder understanding, but it also doesn't enrich the parameter meaning.

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

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

The description clearly states the tool's purpose: a composite check for 'should I add this npm package to my project', fanning out to deps.dev and bundlephobia. It specifies the exact inputs (npm package) and distinguishes itself from alternatives by noting NPM-only support and pointing to deps.dev directly for other ecosystems. The verb 'scan' and resource 'dependency' are well-defined and 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?

The description explicitly provides usage guidance: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also clearly states the limitation and alternative: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly', giving an explicit when-not-to-use and an alternative path. This is exemplary guidance.

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

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

The description discloses specific behavioral details beyond the readOnly/openWorld annotations: it mentions returning 'character offsets and similarity scores', the embedding model 'BGE-base-en embeddings + cosine over 500-char overlapping windows', and the 'cap is 200K chars (longer inputs are truncated and flagged)'. These details inform the agent about output structure and limitations.

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

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

The description is compact yet information-dense, covering purpose, usage example, when-to-use, integration, and technical specs in five sentences. Each sentence contributes unique information, with no filler or redundant claims.

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

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

Given the tool's moderate complexity (3 params, no output schema), the description covers all essential aspects: purpose, input examples, output format (top-N passages with offsets and scores), use case, integration with a sibling, and a critical constraint (200K char cap with truncation flag). It is sufficient for an agent to correctly invoke the tool 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 already provides comprehensive descriptions for all 3 parameters (100% coverage). The description's prose ('Pass the text you already pulled... plus a natural-language query') largely restates the schema. While it adds example contexts (SEC 10-K, article, tool result), these are illustrative rather than essential for parameter understanding. Thus 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 opens with 'Semantic search INSIDE a fetched record', specifying a clear verb ('search') and resource ('fetched record'). It distinguishes itself from siblings by emphasizing that it operates on already-pulled text, unlike broader tools like ask_pipeworx. The phrase 'get back the top-N passages' clarifies the deliverable.

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

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

Explicitly states 'Use when the record is too big to cram into the prompt' and suggests pairing with 'ask_pipeworx_grounded', explaining the workflow: 'fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear when-to-use and alternative usage 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?

Beyond annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds significant behavioral context: auth requirements, non-persistence for anonymous/BYO users, delivery channel details (SMS cap, webhook auto-disable after 10 failures), and the one-time webhook signing secret. 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 dense but well-organized, front-loading the core purpose and then expanding into types and delivery channels. While it is a long paragraph, every sentence adds valuable information; a bulleted structure would improve scannability but is not essential.

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 complex tool with nested objects and no output schema, the description is exceptionally complete. It explains the return value (subscription id), prerequisites, supported types with examples, delivery options with limitations, and consumption methods (recent_alerts, public JSON endpoint).

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 substantial meaning beyond the schema: concrete examples for each subscription type, nested param structures, and critical constraints like phone verification and the 10/day SMS cap. This transforms the parameters from mere fields to actionable guidance.

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

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

The description opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It clearly distinguishes this tool from siblings like list_subscriptions, unsubscribe, and recent_alerts by focusing on the creation action.

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

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

The description provides clear context for when to use the tool, including prerequisites (Pipeworx OAuth account) and supported subscription types with examples. It does not explicitly name alternative tools for when not to use it, but the context is strong enough to imply the correct usage.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds valuable context beyond these: it returns category-bucketed examples, each with the exact tool and argument shape, drawn from the live catalog. No contradictions.

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

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

The description is long but densely informative. It front-loads the key purpose and then packs categories, usage modes, and context into a flowing paragraph. Every sentence contributes; no filler, but it could be tightened slightly for readability.

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

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

For a simple optional-parameter tool with no output schema, the description fully covers what the tool does, what it returns, how to invoke it, and when to use it. There are no remaining gaps for an agent to guess.

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

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

Schema coverage is 100% for the single 'topic' parameter. The description goes further by listing example values ('finance', 'pharma', 'betting') and explaining the default behavior (omit for cross-category). This adds practical meaning beyond the schema.

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

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

The description opens with a clear verb+resource: 'suggest questions' for Pipeworx. It explicitly distinguishes itself from sibling tools like ask_pipeworx by positioning itself as the onboarding entry point that returns example questions with tool call shapes, not answers. This is specific and unambiguous.

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

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

Provides explicit when-to-use: 'Use this FIRST when you do not yet know what Pipeworx can do for you.' It also gives actionable guidance on calling with no arguments vs. passing a topic. It stops short of naming alternatives like ask_pipeworx directly, but the context strongly implies the distinction.

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

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

Adds substantial behavioral context beyond annotations: ownership enforcement, deactivation instead of deletion, and the link to recent_alerts for historical events. This complements the annotations (e.g., destructiveHint=false) without contradicting them.

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

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

Compact two-sentence structure: first sentence states the action, second covers ownership and side effects. Every word earns its place; no filler or repetition.

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

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

For a single-parameter cancellation tool with annotations, the description fully covers the action, constraints, side effects, and downstream visibility. No gaps remain for typical usage.

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

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

Schema description coverage is 100% for the single parameter, including its provenance (returned by subscribe). The description adds no new parameter semantics, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Cancel a subscription by id.' It further clarifies ownership enforcement and the deactivation behavior, which distinguishes it from sibling tools like subscribe and list_subscriptions.

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

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

Provides clear context: only own subscriptions can be cancelled, and cancellation deactivates the row rather than deleting it. While it doesn't explicitly name alternative tools or when-not-to-use conditions, the constraints are made obvious.

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 goes well beyond annotations by explaining the meaning of each verdict type, especially the critical distinction between 'could_not_verify' (check did not happen, carries error details) and 'unsupported' (we looked, no source). It also discloses the two processing paths and that it replaces 4–6 sequential calls. Annotations are not contradicted and are enriched by this context.

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

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

The description is long but every sentence carries weight—no fluff. It front-loads with concrete query examples and then covers behavior and caller warnings. A slight deduction for density; the text could be broken into shorter chunks for easier parsing, but it is still well-structured.

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

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

For a tool with two parameters, no output schema, and no nested objects, this description is exceptional. It fully explains the return values (verdict, actual value, citation, reasoning), error semantics, and routing behavior. An agent has everything needed to invoke and interpret results correctly.

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

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

Schema coverage is 100%, but the description adds meaningful semantics: it defines what 'tolerance_pct' does, explains how it overrides claim wording and provides recommended values for hallucination detection (1–2). It also clarifies the default behavior (capped at 5). This goes beyond the schema's bare 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 the tool performs 'natural-language claim verification against authoritative sources' with a specific verb (verify) and resource (claims). It differentiates from siblings by providing example invocation phrases and explicitly covering both company-financial claims and any other factual claim.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct,' giving clear context. It also describes the internal routing logic (SEC EDGAR fast path vs. grounded pipeline), but it does not name sibling alternatives or state outright when not to use this tool, so it misses full when-not/alternative guidance.

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