Github_private

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

Annotations already cover read-only and idempotent hints. Beyond that, the description adds valuable behavioral context: default model selection, free vs BYO key cost implications for Anthropic, and the exact return shape ({score, confidence, signals, raw_response}).

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 main purpose, then key operational details, then use cases. 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?

Despite having no output schema, the description explains the return format, covers all parameters, lists supported models, and gives concrete use cases. It's complete for a low-complexity read-only tool.

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

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

Schema has 100% parameter description coverage, so baseline is 3. Description supplements this by explaining the default model and clarifying that _apiKey is only needed for Anthropic, but it doesn't fundamentally alter parameter understanding.

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

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

Description opens with a specific verb and resource: 'Probe one or more LLMs for what they know about a business / brand / product / topic and score visibility (0-100) per model.' This clearly distinguishes it from siblings like ask_pipeworx (asking questions) or deep_research (general 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 clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring'), which frames when to use it. However, it doesn't explicitly state when not to use it or contrast with alternative tools.

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

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

Annotations already mark this as read-only, idempotent, and open-world. The description adds valuable behavior context: routing to internal tools, filling arguments, returning pipeworx:// citation URIs, working on every tier, and being one fast call. No contradiction with annotations.

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

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

The description is long but well-structured and information-dense. Every sentence contributes use cases, alternatives, or behavioral context. Minor redundancy exists but does not detract from usefulness.

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 no output schema, the description is remarkably complete: it explains the output format (structured answer with citations), scope (5,529 tools across 1455 sources), when to use, when to use alternatives, and provides examples. Fully equips an agent to choose 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?

Schema coverage is 100% with all aliases documented. The tool description reinforces this by explaining that the input is a natural language question and provides concrete examples (e.g., 'current US unemployment rate'), adding practical value beyond the schema.

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

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

The description clearly states the tool's function: routing questions to 5,529 tools and returning structured answers with citations. It explicitly differentiates from siblings like ask_pipeworx_grounded and deep_research, and even advises against web search.

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 ('what is', 'look up', 'find', etc.), states 'START HERE for most questions', and names alternatives with specific conditions for stepping up (ask_pipeworx_grounded for hallucination resistance, deep_research for broad questions).

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 read-only, idempotent, open-world, and non-destructive traits. The description adds valuable behavioral disclosure about dynamic candidate routing improvements being enabled live during tests, the current absence of a candidate, and that results are compared with the stable router. This goes beyond the annotations by revealing experimental volatility and providing a specific retirement date.

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 and front-loads the key 'Beta version' concept. While it includes a specific retirement date that adds length, each sentence provides necessary context about identical behavior, current status, and usage guidance—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 lack of an output schema, the description references 'same response shape' as ask_pipeworx, which is adequate if the stable tool is known. It covers the experimental nature, current no-op status, and usage sufficiently for a router with many underlying tools, but relies on external knowledge of ask_pipeworx for detailed response expectations.

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

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

Schema coverage is 100% with descriptive aliases for the single `question` parameter. The description does not add parameter-specific meaning beyond stating 'same arguments' as ask_pipeworx, which the schema already covers. 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 it is a beta version of ask_pipeworx, identifying it as an identical universal router with the same 5,529 tools, arguments, and response shape. It explicitly differentiates from the stable ask_pipeworx by being the experimental edge with candidate routing improvements, making its purpose distinct.

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

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

The description 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. It also clarifies the current status (no active candidate) and that it is a full working router, not a fallback, providing clear guidance on when to invoke 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 goes far beyond annotations by disclosing the exact return structure on success and failure, including refusal reasons, and notes the extra LLM call cost. It aligns with annotations (readOnlyHint=true, idempotentHint=true) and adds behavioral nuances like 'EXTRACTS the answer using ONLY what the tool result contains' and explicit refusal cases. No contradiction found.

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

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

The description is dense but well-structured, front-loading the core value proposition. Every sentence contributes meaningful information (routing, extraction, return format, usage, cost). It is slightly long but appropriately detailed for a tool with no output schema; it would merit 5 if slightly trimmed.

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

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

Given the complexity (routing across 5,529 tools) and lack of output schema, the description is remarkably complete. It specifies the return schema on both success and failure, explains refusal reason categories, notes performance implications, and states when to use alternatives. This is sufficient for an agent to invoke the tool with proper expectations.

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

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

Schema description coverage is 100%, with all parameters clearly documented as aliases for 'question.' The tool description adds context about the question's purpose (high-stakes, factual grounding) but does not provide additional parameter-level semantics beyond what the schema already states. Baseline 3 applies because the schema does the heavy lifting.

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

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

The description clearly identifies the tool as a hallucination-resistant answer mode for high-stakes reads, explicitly distinguishing it from ask_pipeworx by emphasizing grounded extraction and evidence. It uses specific verbs like 'extracts' and 'returns' and names the resource (tool results) and output format, making its purpose unambiguous.

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

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

The description 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 ask_pipeworx for casual lookups. This gives clear when-to-use and when-not-to-use 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 claim read-only, idempotent, and open-world behavior. The description goes far beyond: it reveals low-confidence short-circuiting ('low_confidence_match'), closed-market status ('market_closed_or_inactive'), spread illiquidity flags, a resolver contract requiring inspection of confidence fields, parent-event extraction, news fallback fields (e.g., '_fallback_attempted'), and cancellation-rule risk. All disclose meaningful runtime behavior without contradiction.

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

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

The description is long (several hundred words) but densely packed and organized with uppercase section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.), making it scannable. Every section explains behavior an agent needs to safely invoke the tool. It is not as tight as possible, but the verbosity is justified by the tool's complexity and rich response envelope.

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 must document return shapes. It does so thoroughly: result.market fields, result.analysis with model_probability/edge_pp, result.evidence keyed by source, parent_event, news fallback flags, status codes, and cancellation rules. The tool is complex, and the description covers all operational states and failure modes, making it complete for an agent to anticipate outcomes.

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 enriches the market parameter with examples of acceptable formats ('slug', URL, question text) and gives fan-out examples relevant to depth, but it does not materially extend the meaning of `depth` or `include_raw` beyond the schema's clear descriptions. It adds minimal new semantic value for the parameters themselves.

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 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call', giving a specific verb+resource. It clearly explains the resolution, classification, and fan-out behavior, and differentiates via stated use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'). This distinguishes it from sibling tools like polymarket_arbitrage or ask_pipeworx.

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

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

It explicitly provides use cases ('Use for...'), plus a classifier list and fan-out examples that clarify intent. However, it does not explicitly state when NOT to use this tool or name alternative tools for exclusions, so it lacks a full explicit when/when-not contrast.

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 reveals concrete behaviors: pulls from SEC EDGAR/XBRL and FAERS, handles off-calendar fiscal years, sorts by primary metric, and returns paired data with citation URIs. This adds substantial 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?

The description is dense but well-organized: trigger examples, preference rule, per-type data details, output format, and performance note. Every sentence adds actionable information, though the length is a bit high. It earns its place with front-loaded examples and structured specifics.

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 explains return format (paired data + citation URIs), sorting behavior, data sources, and fiscal-year handling. For a 2-parameter tool with rich annotations, this provides complete operational context for an agent to invoke 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?

Schema coverage is 100%, so baseline is 3. The description gives examples and data-source details, but these largely reiterate or supplement what the schema already states (e.g., tickers vs. drug names). It adds some value by explaining what each type returns, but does not deeply enhance parameter syntax or constraints.

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

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

The description opens with natural-language trigger phrases and explicitly states a side-by-side comparison of 2–5 companies or drugs in one call. It clearly identifies the action (compare) and the resource (entities), and distinguishes itself from sequential single-pack lookups and sibling tools 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?

It explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear when-to-use rule and alternative. It also differentiates between type="company" and type="drug" data sources, helping the agent decide when each mode is appropriate.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), the description discloses account requirements, paid-tier for 'thorough', the never-invented gaps[] field, citation_uri only when fetchable, contradictions[] for standard/thorough, semantic excerpting, and latency expectations. No contradiction with annotations.

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

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

The description is a dense, long block of text that, while informative, is not well-structured and repeats some information already in the schema (e.g., depth semantics) and mentions ask_pipeworx multiple times. It is not concise, though nearly every sentence earns its place; a more structured layout would improve 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?

The tool is complex and lacks an output schema, but the description fully covers the return format (findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation), gaps[], contradictions[], hop field, citation_uri conditions, semantic excerpting, and timing. It leaves no major behavioral aspect unexplained.

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, but the description adds real meaning: it explains that 'question' can be broad/multi-part ('decomposition is the point') and elaborates the depth parameter's behavioral nuance beyond the schema's enum descriptions (e.g., what 'standard' and 'thorough' add in terms of gap recovery and contradiction scan).

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 with a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' that 'decomposes your question into focused facets' and routes to 5,529 tools in parallel. It explicitly distinguishes itself from open-web search and contrasts with ask_pipeworx, 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 gives explicit when-to-use guidance and alternatives: 'If you are not signed in, use ask_pipeworx instead', 'Best for broad/multi-part questions over structured data', and for breaking/current-news topics 'prefer ask_pipeworx'. It even specifies the alternative for single lookups, leaving no ambiguity about scope.

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

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

Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable behavioral detail: returns top-N tools with names, descriptions, full input schemas, and curated examples, and that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations to explain the output format and efficiency benefit.

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 purpose and is a single coherent paragraph. The long domain list is somewhat verbose but earns its place by setting expectations of coverage. Each sentence contributes to usage context or return behavior; no filler is present.

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 explains what is returned (top-N tools with schemas and examples) and the benefit of direct callability. Combined with complete input schema and annotations, the tool is fully specified for an agent to invoke correctly.

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

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

Schema coverage is 100% with all parameters documented, including aliases and examples. The description itself does not add parameter-level detail beyond what the schema provides (e.g., it says 'describing the data or task' but doesn't mention the limit parameter or aliases). Baseline 3 is appropriate since the schema carries the heavy lifting.

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

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

The description opens with a specific verb+resource ('Find tools by describing the data or task') and enumerates the scope (SEC filings, financials, FDA drugs, etc.). It clearly differentiates from siblings as the meta-discovery tool by stating 'Call this FIRST' and framing the return as a set of options rather than one answer.

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

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

Explicit usage guidance: 'Use when you need to browse, search, look up, or discover what tools exist' and 'not just one answer' gives a when-not. 'Call this FIRST when you have many tools available' provides a clear directive and implicitly recommends this before falling back to specific tools.

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

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

Beyond annotations (read-only, idempotent, etc.), the description discloses internal fan-out to SEC EDGAR, XBRL, USPTO, news, GLEIF, return structure, and a soft-fail for patents due to API sunset. It mentions parallelism and failure behavior, adding significant transparency.

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

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

The description is longer than average, but the length is justified by the tool's complexity. It front-loads examples and the core statement, then details outputs and limitations. Some redundancy in examples, but overall efficient.

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

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

With no output schema, the description fully specifies return fields (cik, recent_filings, fundamentals, patents, news, LEI) and their formats. It also covers limitations and fallbacks, making the tool's behavior predictable 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 baseline is 3. The description repeats the value format (ticker vs CIK) and the names-not-supported rule, matching the schema. It adds no new parameter-specific information beyond what the schema already provides.

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

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

The description clearly states it produces 'full cross-source profile of a US public company in ONE parallel call,' with explicit examples of user queries and output contents. It differentiates from siblings like resolve_entity by noting names are not supported and directing to use resolve_entity first.

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

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

Explicitly tells when to use: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups.' Also gives an alternative: 'use resolve_entity first if you only have a name.' This is clear context and exclusions.

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

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

Annotations already disclose destructive (destructiveHint: true), read-only (readOnlyHint: false), and idempotent (idempotentHint: true) behavior. The description adds that it deletes a memory by key, which is the primary behavior, and mentions sensitive data context. However, it does not explain what happens if the key does not exist or whether deletion is irreversible, leaving some behavioral details implicit.

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, no fluff. The first sentence states the core purpose, and the second provides usage guidance and sibling pairing. Every word earns its place, and the description is appropriately front-loaded with the action.

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

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

For a simple single-parameter tool, the description is complete. It explains what it deletes, when to use it, and how it relates to remember and recall. The annotations cover safety and idempotency, and the schema covers parameters. No output schema exists, so no return-value explanation is needed.

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

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

The input schema already covers 100% of the parameters, with the 'key' property described as 'Memory key to delete.' The description only contributes the phrase 'by key,' which does not add meaningful semantics beyond the schema. Baseline score of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the action: 'Delete a previously stored memory by key.' The resource is a memory, and the method is deletion via a specific key. It also distinguishes itself from sibling tools 'remember' and 'recall' by explicitly pairing with them, showing it is the complement for forgetting.

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: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names the alternatives 'remember' and 'recall' for storage and retrieval, respectively. It lacks an explicit when-not-to-use statement, but the alternatives are clear enough.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds behavioral detail by stating it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format' and that output is 'a single text blob ready to drop at site-root/llms.txt.' This provides process and output context 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, each earning its place: the first states the main purpose, the second explains the process, and the third lists use cases. It is front-loaded with the most critical information and contains no unnecessary detail.

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 (two parameters, one required), comprehensive annotations, and no output schema, the description is complete. It explains the what, how, and when, and describes the output format ('single text blob') which is important in the absence of an output schema.

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

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

The input schema provides full descriptions for both parameters (url and max_links), covering 100% of the parameter semantics. The description does not add additional meaning for these parameters, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL' and explains the process of fetching, extracting, and emitting markdown. The verb 'generate' and resource 'llms.txt' are specific. However, it does not explicitly distinguish this tool from sibling tools like scan_competitor_ai_presence, even though it mentions a similar use case (auditing a competitor).

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives strong context for when to use the tool. However, it does not mention alternatives or explicitly state when not to use it, so it falls short of full guideline coverage.

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 the safety profile. The description adds 'Returns raw content and metadata,' which is useful, but it does not provide deeper behavioral context such as authentication needs, rate limits, or edge cases. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with an example, containing no superfluous information. It is concise yet covers the essential purpose and parameter specification.

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 straightforward file retrieval tool, the description is complete given the presence of a full input schema, output schema, and thorough annotations. It tells the user what to specify, what the tool does, and what it returns, which is sufficient for selection and invocation.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters (owner, repo, path, ref). The description adds an example path ('README.md') and restates the need to specify owner, repo, and path, but does not add significant meaning beyond what the schema provides.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'Get file contents from a repository.' It also specifies the required scope (owner, repo, file path) and gives an example. This distinguishes it from sibling tools like gh_get_repo (repository metadata) and gh_list_* (listings).

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

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

The description implies usage by stating what the tool does and what parameters to specify, but it does not explicitly say when to use this tool versus alternatives. There is no mention of exclusions or alternative tools, so it provides only implicit 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, openWorldHint, and idempotentHint, covering safety. The description adds value by specifying the returned fields (description, language, stars, forks, open issues, default branch, access level), which is useful context but does not disclose additional behavioral traits like rate limits or auth.

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 front-loads the core purpose and includes a list of return fields. No wasted words.

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

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

The tool is a simple read operation with full schema coverage, annotations, and an output schema. The description provides enough detail for the agent to select and invoke it correctly, and it aligns with sibling tool boundaries.

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 fully documents the two parameters (owner, repo) with descriptions. The tool description adds no further parameter detail, but the baseline is 3 given 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 detailed info') and the specific resource ('for a specific repository'), and lists key return fields. This distinguishes it from siblings like gh_list_repos, which enumerate repositories.

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

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

The description implies usage for a specific repository, contrasting with list-type siblings, but does not explicitly name alternatives or exclusions. The context is clear enough for an agent to choose this tool over gh_list_repos when a single repo's details 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 the tool as read-only, idempotent, and non-destructive. The description adds return field details (titles, numbers, status, assignees, labels) and an example, but since an output schema exists, this is redundant. No additional behavioral traits like auth requirements or rate limits are mentioned.

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 concise sentences, front-loaded with the core verb-resource statement, and includes a practical example. No wasted words.

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

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

The description is sufficiently complete given the annotations and output schema. It covers the essential purpose and parameter usage. A minor omission is a note about pagination behavior, but per_page is described in the schema, so the context is adequate.

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

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

Schema coverage is 100% with clear descriptions for all four parameters. The description's example reinforces the schema but adds no new semantic meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states 'List issues in a repository' with a specific verb and resource, and includes example parameters. It distinguishes itself from sibling tools like gh_list_pulls and gh_list_repos by naming the resource type explicitly.

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

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

The description provides clear context for when to use the tool (to list issues) and shows examples of filtering by state and pagination. It does not explicitly mention alternatives or exclusions, so it misses the top score, but the intent is unambiguous.

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 read-only, idempotent, non-destructive behavior. The description adds value by disclosing the return payload fields (org names, URLs, role), which is beyond the annotations. It also implies the scope is restricted to the authenticated user's memberships, adding 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 a single, dense sentence that front-loads the primary action ('List organizations you're a member of') and then specifies return values. No wasted words, perfectly concise for the tool's simplicity.

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

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

Given the tool has no parameters, a rich output schema, and strong annotations, the description is fully complete. It states what is listed and what fields are returned. There are no gaps in prerequisites, side effects, or complex 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 tool has zero parameters, so the schema provides no semantics to clarify. Baseline for 0 params is 4; the description does not need to compensate. It adds no parameter-related details, but none are required.

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 organizations the user is a member of, with a specific verb ('List') and resource ('organizations'). It distinguishes from siblings like gh_list_repos and gh_list_issues by the object type. The added detail about returning org names, URLs, and roles sharpens the 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 implies when to use the tool—when you need your GitHub organizations—but does not explicitly state alternatives or exclusion criteria. No mention of when not to use it or more specialized alternatives. It is a simple, self-evident tool, but lacks explicit guidance compared to the 'get_calls' example.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds value by specifying the exact return fields (titles, numbers, status, reviewers, merge state) and emphasizing the need to supply owner/repo, which goes beyond the annotated safety profile.

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 that front-load the action, include a practical example, and summarize return fields. No wasted words.

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

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

The tool has a rich output schema and annotations, and the description complements them by clarifying the returned data and parameter usage. It is fully adequate for this straightforward list operation.

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 schema already documents all four parameters. The description adds an example and reinforces the owner/repo requirement, but doesn't provide additional semantic details beyond the schema.

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

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

The description clearly states the verb and resource: 'List pull requests in a repository.' It specifies the necessary owner and repo parameters and lists the returned fields, distinguishing it from sibling tools like gh_list_issues.

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 (listing PRs in a repo) with an explicit example of parameters. It doesn't mention exclusions or alternatives, but the usage is unambiguous.

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, establishing a safe read operation. The description adds helpful context by specifying that private repos are included and enumerating the returned fields, which goes beyond the annotations. It does not discuss rate limits or authentication, but with annotations present, this is adequate.

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 that states the action and return value. It is concise, with no redundant phrases or unnecessary details, every word earns its place.

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

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

The tool has rich annotations, a fully described input schema, and an output schema available. The description covers the core behavior and return fields, which is sufficient for a simple list tool. It lacks explicit usage exclusions or mention of pagination defaults, but these are not critical given the schema and typical use case.

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 full descriptions for all three parameters (sort, per_page, visibility) with 100% coverage. The tool description does not add any parameter semantics beyond the schema, 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 a specific verb ('List') with a clear resource ('your repositories'), includes scope ('including private ones'), and lists return fields. This distinguishes it from sibling tools like gh_list_issues and gh_list_pulls, making it unambiguous what the tool does.

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

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

The description implies usage for listing repositories but does not explicitly mention alternatives or conditions for when not to use it. Sibling tool names provide some differentiation, but there is no direct guidance such as 'for a single repo, use gh_get_repo'.

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 read-only, idempotent, non-destructive behavior. The description adds useful context about the return fields (id, type, params, etc.) and the 'active' filter, 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?

Two sentences, front-loaded with the action and key details, and no fluff. Every word earns its place.

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

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

The tool is simple with one optional parameter and no output schema. The description explains the return shape and use case, making it complete enough, though it doesn't mention edge cases like pagination or list length limits.

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 fully describes the single parameter (include_inactive) with its default and meaning, so the description doesn't need to add much. It implicitly relates to 'active subscriptions' but doesn't explicitly discuss the parameter.

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

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

The description uses a specific verb ('List') and resource ('subscriptions'), and clarifies scope: 'the caller's active subscriptions'. This clearly distinguishes it from siblings like subscribe/unsubscribe.

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

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

It provides clear usage context: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives an explicit use case but does not state when not to use it or mention alternatives explicitly.

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 the annotations by explaining that filing without an account returns a claim_token, that passing it back later reads the status, and that the tool is rate-limited to 5 per day and free. It discloses behavior 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 longer than average but front-loaded with purpose and usage. Every sentence adds useful detail (rate limits, claim_token flow, scope restrictions), so it earns its length, though some trimming of quota/free wording could tighten it.

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 nested optional parameters and no output schema, but the description covers the full workflow: when to use, how to frame feedback, the claim_token flow, and rate limits. It is behaviorally complete for an agent to invoke this 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 100% of parameters, so baseline is 3. The description adds value by explaining the claim_token round-trip pattern ('pass it back later as pipeworx_feedback({claim_token:...})') and advising users to describe issues in terms of Pipeworx tools/packs, which adds 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 'Tell the Pipeworx team something is broken, missing, or needs to exist,' giving a specific verb and resource. It clearly distinguishes this from siblings by framing it as feedback about Pipeworx tools only, not research or data tools.

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

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

The description explicitly says when to use it: for bugs, feature/data gaps, or praise. It also gives a clear exclusion: 'if the tool came from a different MCP server... file it with that server instead.' This is exemplary usage guidance with 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?

Adds valuable context beyond annotations: data source (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h depending on window). This enriches the agent's understanding of freshness and safety without contradicting the readOnlyHint.

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

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

The description is well-structured, with a clear opening statement, an explicit 'Useful for' list, and a concise note on data source and caching. Every sentence adds value, and it's neither too long nor repetitive.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers what it returns, why it's useful, and relevant behavioral details. 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 coverage is 100%, and the schema already describes the window parameter's meaning and defaults. The description adds cache timing tied to window but no substantial new parameter semantics beyond what the schema provides.

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

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

The description clearly states the tool's function: returns the top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources, distinguishing it from sibling tools like discover_tools by emphasizing the aggregated signal from other AI agents.

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 three explicit use cases, including discovering hot data sources, confirming canonical choices, and aligning use cases. While it doesn't name alternative tools, the context is strong enough for an agent to know when to invoke this tool.

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

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

Annotations only declare readOnly/openWorld/idempotent, but the description discloses rich behavioral context: the Jaccard similarity threshold (≥0.30), placeholder fraction filter (>20% returns null), partition deviation >3pp triggering BUY/SELL EVERY LEG, and the fill check using live CLOB depth. The warning 'realizable_edge_pp ≤ 0... do not trade it' is a critical safety detail beyond any annotation.

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

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

The description is long and dense, but well-structured with labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with core purpose and invocation modes. Some redundancy exists with the schema, but the length is largely justified by the tool's complexity.

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

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

Given the absence of an output schema and the tool's complexity, the description covers the return shape (opportunities[] fields), the partition_check object, fill check behavior, and edge cases like placeholder slugs and low similarity pairs. It even warns against trading when the edge is not realizable, making it near-complete for agent decision-making.

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

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

While the schema covers both event and topic parameters well, the description adds the critical no-args trending_scan mode, which is not in the schema. It also clarifies event accepts slugs or full URLs and topic uses seed questions with concrete examples, adding meaning beyond the schema's already strong 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 opens with a specific verb-resource pair: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly states what the tool does and distinguishes it from siblings like polymarket_edges or polymarket_fill_risk. The three invocation modes (trending_scan, event, topic) further clarify the exact scope of each use case.

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 differentiates when to use event vs. topic modes, recommending event for a specific market and topic for cross-event scanning. It also notes that cross-event mode catches date-boundary patterns that single-event mode misses, and explicitly directs users to polymarket_fill_risk for custom sizing, providing clear 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 flag readOnly/idempotent, but the description adds rich behavioral detail: slippage is subtracted from edge, Kelly fractions are capped, placeholder slugs are filtered, per-sport alpha values are disclosed, diagnostics reveal why segments are empty, and a 24h-move warning is included. It also notes the 1h KV caching. 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 an extremely long, dense technical specification. It front-loads the purpose well, but then packs model-family details, per-sport alpha values, placeholder filter rules, response field lists, and caching behavior into a wall of text. Many sentences could be moved to an output schema or supporting docs, making it not appropriately sized for quick agent scanning.

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 must explain what is returned. It thoroughly covers the response top-level structure (by_segment, fed_candidates/fed_note, _diagnostics), per-opportunity fields (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h warning), and how knobs affect the output. It also explains why segments might be empty, making it fully complete 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 the baseline is 3. The description adds meaningful beyond-schema semantics: it explains the tradeable-edge knobs (min_liquidity/max_spread_pp), clarifies that min_partition_leg_kelly applies per-leg while min_kelly applies single-leg, and gives context for slippage_pp (zero fees but 20-50bp typical execution cost). Some params like limit/window/category_filter are not individually elaborated, so not a 5.

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 opening sentence has a specific verb ('Scan'), resource ('top Polymarket markets'), and outcome ('return opportunities where Pipeworx data disagrees with market price'). The 'what should I bet on today' use case and the detailed model-family breakdown clearly distinguish it from sibling tools like polymarket_arbitrage or polymarket_edge_tracker.

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 states the intended scenario ('Built for what should I bet on today') and the advantage ('without paging hundreds of markets'), giving a clear use context. However, it does not explicitly name alternatives or say when not to use this tool versus a sibling, so it stops short of full 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?

Despite comprehensive annotations (readOnly, idempotent, non-destructive), the description adds substantial behavioral detail: response structure (tracked, expired, snapshot_dates), computation specifics (trend based on |edge_pp_net|, decay from daily closes), and limitations (60-day TTL, cache-miss snapshot writes). This far exceeds the annotation baseline and provides rich operational 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 tightly organized: a one-sentence purpose, then labeled sections (Args, RESPONSE, LIMITS). Every sentence adds unique value—no fluff or repetition of schema. The front-loaded purpose ensures immediate clarity, and the structured format makes it easy to parse.

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 (time-series analysis, multiple response categories, subtle edge cases) and the absence of an output schema, the description is exceptionally complete. It covers return fields, how to interpret trend/decay, snapshot gaps, and historical boundaries, leaving little ambiguity 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%, but the description adds meaning by explaining 'days' as lookback with default/max values and 'window' as the snapshot family ('24hr | 1wk | 1mo'). It also connects parameters to the underlying data source (daily polymarket_edges snapshots), which helps an agent understand the impact of different choices.

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

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

The description clearly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It uses a specific verb ('answers') and resource (edge persistence/decay) and distinguishes itself from siblings like polymarket_edges by focusing on historical tracking rather than current edge calculation.

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 ('a fresh wide edge and a 3-week-old wide edge are different trades'), implying it's for assessing edge persistence over time. It does not explicitly name alternatives or state when not to use it, but the context is strong enough for an agent to infer appropriate usage.

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

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

Beyond the readOnlyHint=true annotation, the description discloses mechanics: 'walks the ladder,' return fields like top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict, and basket-mode behaviors including per-leg details and forced_directional_risk. It also notes defaults and clamping. No contradiction with annotations.

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

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

The description is dense and front-loaded with purpose, and every clause adds operational value. It is a single long paragraph that could benefit from bulleted sub-sections for single/basket modes, but it remains appropriately sized for the tool's complexity with no redundant 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?

With no output schema, the description compensates by enumerating return fields for both modes, explaining defaults, clamping, and failure semantics. It also covers use-case context, risk warnings, and integration with sibling tools, making it fully self-sufficient 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?

Although schema coverage is 100%, the description enriches parameter meaning: it explains size_usd as 'max spend on buys, target proceeds on sells' in single-market mode and 'settlement notional' in basket mode, clarifies side defaults, and states the mutual exclusivity of market vs event. 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 specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes from siblings by explicitly referencing polymarket_arbitrage and polymarket_edges and positioning this tool as the pre-trade risk check.

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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains when theoretical edges are not capturable and warns about partial fills, effectively stating when not to rely on theoretical values.

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 a read-only, idempotent, non-destructive operation, but the description adds extensive behavioral detail: how compatibility_warning triggers, temporal_alignment meaning, skipped_cross_type/subtype counters, and the exact conditions under which spreads are meaningless. This goes far beyond what annotations provide and helps the agent interpret the response safely.

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

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

The description is lengthy but densely informative. It uses clear markers like 'TWO MODES,' labels for response fields, and explicit caveats. While it could be broken into bullet points for easier scanning, every sentence carries meaningful information relevant to correct invocation and interpretation.

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

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

Given the absence of an output schema, the description compensates thoroughly by enumerating response components (leg-by-leg prices, spread list), safety fields, and the semantic conditions around temporal alignment and skipped pairs. For a cross-venue tool with nuanced matching logic, this is nearly 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 schema already documents all three parameters at 100% coverage, so the baseline is 3. The description adds value by explaining parameter interactions: topic auto-fetches matching events on both venues, and explicit tickers override the topic-mapped side. This extra context clarifies how to combine or switch between parameters, which is not evident from 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 opens with 'Cross-venue spread between Kalshi and Polymarket for the same resolving question,' clearly identifying the tool's function and object. It goes beyond a generic phrase by detailing two modes and the response structure, distinguishing it from related siblings like polymarket_arbitrage or polymarket_edges.

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

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

The tool explicitly explains two usage modes (topic shortcuts vs explicit tickers) and warns that most pre-mapped topics currently return compatibility_warnings, helping the agent decide when to rely on results. It does not explicitly name alternative tools, but the context of when to use each mode and the caveat that 'pre-mapped ≠ tradeable' provides strong implicit guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description does not contradict them. It adds behavioral context beyond annotations by explaining scope: 'Scoped to your identifier (anonymous IP, BYO key hash, or account ID).' It also describes the dual behavior (retrieve vs. list), which is useful.

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. Every sentence earns its place: purpose, usage context, scope, and tool pairing. No unnecessary words.

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

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

For a simple one-parameter, read-only tool with no output schema, the description is complete. It covers the operation, when to use it, scope, and companion tools. The behavior for omitting the key is described in both schema and description, leaving no major gaps.

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

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

Schema coverage is 100%, and the schema describes the 'key' parameter as 'Memory key to retrieve (omit to list all keys).' The description adds meaning by providing concrete examples of keys (target ticker, address, research notes) and reinforcing the omission behavior. This adds value beyond the schema.

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

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

The description states a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument).' It clearly distinguishes the tool from siblings like remember and forget by focusing on retrieval and listing, and even names the paired tools.

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

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

It explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also provides clear guidance on the relationship with alternatives: 'Pair with remember to save, forget to delete.' This gives both context and exclusions.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds important context: setting mark_read:true mutates read state so future calls return only newer events, and that polling is safe. It also mentions the external URL for the same feed, which is extra behavioral context not in 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 compact and front-loaded with the main action. All sentences provide useful information—return structure, filtering, side effects, and an alternative access method. It is slightly longer than strictly necessary but avoids redundancy and stays 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?

With no output schema, the description adequately covers return contents (source, citation_uri, payload) and key behaviors. It also explains mark_read semantics and provides an external access option. Gaps such as error handling or pagination parameters are not covered, but for this tool's complexity the description 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?

The schema already covers 100% of parameters with descriptions. The description adds extra semantic value by giving a concrete example for 'type' (sec_8k), explaining the effect of 'mark_read' (flags events as read and affects subsequent calls), and clarifying that 'since' uses ISO timestamps. This goes beyond the schema's basic descriptions.

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

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

The description clearly states what the tool does: 'Pull fired events from your subscription feed' and specifies the return contents (source, citation_uri, raw event payload). It distinguishes itself from siblings like recent_changes by focusing on subscription alerts and referring to 'the evaluator has written to your persisted feed'.

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 mentions that polling is acceptable and provides an alternative: 'the same feed is also at GET registry.pipeworx.io/alerts.json for scripts and dashboards.' This gives clear guidance on when to use the tool versus the HTTP endpoint. It also explains filtering by type and since, and the mark_read option for incremental reads.

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 the multi-source fan-out (SEC, GDELT/GNews, USPTO), the fallback logic on rate limits/5xx, and the patent API sunset issue. It also clarifies the return structure (changes[] grouped by source, total_changes, citation URIs), which is not present in 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 information-dense and each section earns its place, but the opening list of example queries is somewhat repetitive and could be trimmed. However, it is front-loaded with purpose and the rest is well-organized, making it appropriate 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?

With no output schema, the description compensates well by summarizing the return format (changes[] grouped by source, total_changes, citation URIs) and covering data source limitations and parameter formats. It also names an alternative tool. The only minor gap is the exact inner structure of each change item, but overall it is complete for the tool's complexity.

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

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

Schema coverage is 100%, but the description adds significant value by explaining the `since` parameter's accepted formats (ISO vs relative shorthand with examples like '7d', '3m') and recommending '30d' or '1m' for typical monitoring. The `value` parameter's ticker/CIK ambiguity is also reinforced. This goes beyond the schema's basic descriptions.

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

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

The description clearly identifies the tool as a change feed for a company over a time window, using specific verbs like 'fans out' and 'returns'. It distinguishes itself from entity_profile by explicitly stating that entity_profile provides static profiles, making the purpose and scope 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 names entity_profile as the alternative when a static profile is needed, and explains when to use recent_changes (for windowed change feeds). It also details the GDELT→GNews fallback and the USPTO soft-fail, giving contextual guidance on expected behavior.

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

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

Annotations already indicate idempotent and non-destructive behavior, but the description adds valuable context: memory is scoped by identifier and persistence differs by auth state (authenticated vs 24-hour anonymous). This goes beyond structured data to explain retention semantics, though it doesn't mention overwrite behavior for existing keys (covered by idempotentHint).

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, followed by usage examples and persistence details. Every sentence contributes unique information with no fluff or repetition of the title.

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 write tool with no output schema, the description covers purpose, when to use, storage scoping, retention policy, and lifecycle companions. It is complete for an agent to confidently invoke the tool without missing critical context.

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

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

Schema coverage is 100% with descriptive parameter explanations ('Memory key (e.g., ...)' and 'Value to store (any text...)'), so the schema fully documents both parameters. The description only adds 'key-value pair' which is already implied, providing no additional semantic value beyond the schema.

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

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

The description clearly states the tool's function: 'Save data the agent will need to reuse later' with a specific verb and resource. It distinguishes from siblings by explicitly pairing with 'recall' and 'forget', making its role in the memory triad clear.

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 triggers ('Use when you discover something worth carrying forward') with concrete examples (resolved ticker, target address, user preference). It also names complementary tools (recall, forget), giving the agent a clear lifecycle context without ambiguity.

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

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

The description discloses behaviors beyond annotations: it mentions that LEI/FIGI enrichment degrades gracefully, that each call cascades through several internal endpoints, and that unresolved identifiers are reported in an `unresolved` field. This level of transparency helps agents predict outcomes and handle partial results.

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 leads with usage examples and a clear purpose statement, then organizes additional details by entity type. Though it's longer than typical, the information density is high and each sentence adds value. A bulleted layout could improve scannability, but the current structure is acceptable.

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

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

Given the absence of an output schema, the description thoroughly covers return values: source-labelled identifiers, explicit unresolved fields, and RxNorm citation links. It also addresses edge cases like unavailable enrichment sources, making it sufficiently complete for agent invocation.

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

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

The schema only labels `type` as an enum and `value` as a string, but the description explains that `company` returns CIK, ticker, LEI, FIGI, and ownership data with source labels, while `drug` returns RxCUI, ingredient, brand, and a citation URL. It also defines acceptable input formats for `value`, such as ticker, CIK, or name, and brand/generic drug names.

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

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

The description clearly defines the tool's action: it resolves user-spoken names to canonical identifiers. It opens with concrete examples like 'What's the ticker for…' and states 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' This specificity and alignment with sibling tools (e.g., entity_profile consumes IDs) give a strong 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 instructs agents to 'Use FIRST whenever you have a name but need an ID,' establishing a clear when-to-use condition. It also details the supported entity types, which helps agents decide if a query qualifies. However, it does not explicitly mention when not to use it or name alternative tools, limiting the 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. The description adds meaningful behavior: it probes each entity via ai_visibility_check, ranks by score, and returns per-entity score, confidence, and signal density. It does not contradict annotations and gives extra orchestration context, though it omits potential costs or latency.

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: purpose, mechanism, and use case with example query. No wasted words, no repetition of schema details, and the most important info is front-loaded.

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

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

For a multi-step tool with no output schema, the description explains the return format (ranked list with score, confidence, signal density) and the brand + competitors framing. Combined with rich schema descriptions and annotations, it gives sufficient context for correct selection and 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 descriptions cover all 4 parameters (100% coverage), including details on 'entities' subject/competitor framing and _apiKey requirements. The description itself adds no further parameter-specific explanations beyond reinforcing the 'entities' meaning, so the 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 'Compares AI visibility across multiple entities side-by-side', specifies the mechanism (probes each entity with ai_visibility_check), and the outcome (ranks by score, surfaces most/least recognized). This distinguishes it from sibling single-entity tools like ai_visibility_check.

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 positions the tool for 'competitive AI-marketing audits' with an example query, implying it is for multi-entity comparisons. However, it does not explicitly say 'use this instead of ai_visibility_check for single entities' or exclude other alternatives, though the phrase 'probes each entity with ai_visibility_check' hints at that lower-level 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?

The description adds significant behavioral detail beyond the annotations, such as graceful degradation on partial failures, a 5-30s first-measurement timeout for bundlephobia, and the fact that sources_failed will list timeouts while the rest still returns. This supplements the readOnly/idempotent hints with operational nuance.

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 carries unique value: purpose, usage, return fields, ecosystem constraint, and failure behavior. It is well-structured, front-loading the core purpose before details, and uses a practical example to illustrate usage.

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 enumerates the return structure (summary block fields, per-advisory detail, links, alternative versions). It covers the tool's scope, limitations, performance characteristics, and error handling, fully equipping an agent to use 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 coverage is 100% with descriptive entries for both package and version, so the description does not need to explain syntax or defaults. It adds minimal new parameter context beyond the schema, but the composite nature of the tool is hinted at, which slightly enriches understanding.

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

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

The description clearly defines the tool as a composite npm package evaluation check, naming specific data sources (deps.dev, bundlephobia) and listing exact outputs. It distinguishes itself from other tools by specifying the NPM-only scope and the alternative approach for other ecosystems.

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

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

Explicitly states when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' Also provides an alternative for other ecosystems: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' making the 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?

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing truncation behavior ('cap is 200K chars... truncated and flagged'), embedding details (BGE-base-en, 500-char windows), and return structure (character offsets, similarity scores). No contradiction with annotations.

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

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

The description is dense and well-structured: core function first, then usage scenario, technical details, and limits. Every sentence conveys useful information without 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 lacking an output schema, the description fully explains return values (top-N passages with offsets and similarity scores). It also covers edge behavior (truncation) and integration with sibling tools, making it complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context by explaining 'text' as 'the text you already pulled' and giving query examples, but doesn't add new parameter-specific syntax beyond the schema. The extra context justifies a slight bump.

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 semantic search inside a fetched record, with a specific verb+resource structure. It distinguishes itself from sibling tools by emphasizing searching within an already-fetched text, and later contrasts with ask_pipeworx_grounded.

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

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

Explicitly says when to use: 'Use when the record is too big to cram into the prompt'. Also provides an alternative pairing: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This provides clear usage context and exclusions.

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

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

Annotations provide readOnlyHint:false and idempotentHint:true, but the description adds substantial context such as the OAuth requirement, SMS 10/day cap, webhook auto-disable after 10 failures, and the one-time signing secret. This goes well beyond the annotations.

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

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

The description is long but well-structured, starting with the purpose and then detailing types and delivery channels. While lengthy, every sentence conveys necessary information for a complex tool with multiple subscription types and delivery options.

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 mentions the return value ('Returns the new subscription id') and covers authentication, all supported types, delivery channels, rate limits, and failure behaviors. It is comprehensive for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches each parameter with concrete examples and constraints, such as 'items:["5.02"] = officer change' and phone verification for SMS. This provides meaning beyond the schema's terse 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 opens with a specific verb+resource: 'Create a proactive monitoring subscription to a live-data event stream.' It further distinguishes itself from siblings like list_subscriptions and unsubscribe by focusing on creation and returning the subscription id.

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

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

The description clearly states activation prerequisites ('Requires a Pipeworx OAuth account') and enumerates supported types with examples, implying when to use the tool. However, it does not explicitly mention alternatives like list_subscriptions or unsubscribe, so it's not a full when/when-not guide.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond these: it returns live catalog data with example questions and tool shapes, and that topic filters the output. It does not contradict annotations and provides useful operational detail (what the response contains, how arguments affect it).

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 packed with useful information: sample user queries, return format, parameter behavior, and usage positioning. It is front-loaded with user intents and remains structured. It could trim the redundant example queries slightly, but every sentence adds clarity.

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

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

The tool is simple (one optional parameter, no output schema), and the description covers its purpose, usage, parameter semantics, and relationship to sibling meta-tools. It explains what the user gets (category-bucketed questions with tool shapes) and when to use it, making the tool fully understandable without external references.

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 the `topic` parameter with allowed values (100% coverage). The description adds semantic value by explaining that omitting `topic` gives a cross-category spread, while passing it focuses results, and gives concrete examples like 'finance', 'pharma', 'betting'. This goes beyond the schema's value list.

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: it's the onboarding entry point for an agent that wants to know what to ask Pipeworx, returning category-bucketed example questions with the exact tool and argument shape for each. It distinguishes itself from siblings by mentioning the meta-tools (ask_pipeworx, entity_profile, compare_entities) and positioning itself as the 'FIRST' step.

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

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

The description gives explicit usage guidance: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains the optional `topic` parameter, telling the user to omit it for a full spread or pass a specific focus area.

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 signal non-read-only and idempotent behavior, but the description adds critical context: the row is deactivated, not deleted, and historical events stay accessible. This clearly explains the side effects beyond what structured annotations convey.

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

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

Two dense sentences front-load the primary action and then provide essential constraints and side-effect details. Every sentence earns its place with no filler or redundancy.

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

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

For a simple single-parameter tool with rich annotations, the description sufficiently covers purpose, ownership, deactivation semantics, and historical availability. No output schema exists, so explaining return values is unnecessary.

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

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

The schema already fully documents the 'id' parameter as a subscription uuid returned by subscribe. The description merely says 'by id' and adds no extra meaning beyond the schema, warranting the baseline score 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 opens with 'Cancel a subscription by id', a specific verb+resource pairing that clearly communicates the action. It also distinguishes itself from siblings like subscribe and list_subscriptions by emphasizing the deactivation behavior and preservation of history.

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 noting ownership enforcement and that historical events remain available via recent_alerts. However, it does not explicitly enumerate alternative tools or state when not to use it, so it falls short of full 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?

Goes well beyond the readOnly/idempotent annotations by disclosing the two execution paths (SEC EDGAR fast path vs. grounded pipeline), the meaning of could_not_verify vs. unsupported, and that it replaces 4-6 sequential calls. 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?

Though long, every sentence earns its place. It front-loads with query examples and purpose, then logically covers routing, return values, and caveats. No redundancy or filler.

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

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

For a tool without an output schema, it fully describes the verdict enum, citation format, reasoning, error semantics (verification_error), and the two processing paths. The agent has enough information 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%, and the description adds extra practical semantics: for tolerance_pct it explains how to override for hallucination detection (1-2), clarifies the default cap of 5, and provides illustrative examples for the claim parameter. This enriches the schema 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 clearly states the tool's purpose: natural-language claim verification against authoritative sources. It gives specific verb-resource phrasing ('verify the claim that...') and distinguishes it from sibling tools by focusing on fact-checking with verdicts, not general Q&A or 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?

Directly says 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides routing guidance for financial vs. other claims and explicitly warns about the could_not_verify state, telling callers not to treat it as evidence.

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