Github

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

Annotations already cover read-only/idempotent/non-destructive, and the description adds valuable context: the default Workers AI model is free, using Anthropic requires a BYO API key and direct payment, and the return format is explicitly described. This discloses cost, external API calls, and output structure beyond what annotations provide.

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

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

Three sentences with a clear front-loaded action statement. Every sentence adds value: what the tool does, model/cost details, return structure, and use cases. No fluff or redundancy.

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

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

Despite no output schema, the description explains the return format ({score, confidence, signals, raw_response} + combined view). It covers the essential parameters, cost implications, and typical use cases, making it sufficiently complete for an agent to decide when and how to invoke the tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning beyond the schema by clarifying the financial model (Workers AI free, Anthropic BYO key) and that passing _apiKey enables Anthropic probing, which is not explicit in the schema. This elevates the score to 4.

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

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

The description clearly states the tool's specific function: probing LLMs for knowledge about an entity and scoring visibility on a 0-100 scale. It uses an action verb ('probe') and concrete resource ('one or more LLMs'), but does not explicitly differentiate from the sibling tool 'scan_competitor_ai_presence', which could overlap in use cases.

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

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

The description provides clear use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains the default model choice with a free option versus using your own API key for Anthropic. It gives practical context for when to invoke the tool, though it doesn't explicitly state when not to use it or name 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful behavioral context: it fills arguments automatically, returns stable pipeworx:// citation URIs, works on every tier, and is a single fast call. It does not contradict annotations, though it omits potential limitations like latency or failure modes.

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 most important directive ('PREFER OVER WEB SEARCH') and structured logically: purpose, usage triggers, examples, escalation paths. It is somewhat verbose but every sentence adds value for a tool with broad scope.

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

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

Given the tool's complexity and lack of output schema, the description covers purpose, typical use cases, examples, and alternatives. It even mentions the return format (structured answer with citation URIs). Minor gaps: no mention of failure scenarios or how to handle ambiguous questions.

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 six parameters described as aliases for 'question'. The description reinforces the natural-language question format with examples but adds no semantic detail beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states what the tool does: it routes questions to one of 5,521 tools across 1,452 verified sources and returns structured answers with citations. It uses a specific verb ('routes') and distinguishes itself from siblings by explicitly naming ask_pipeworx_grounded and deep_research as alternatives.

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

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

The description provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and step-up conditions ('for a hallucination-resistant single answer... use ask_pipeworx_grounded; for a broad/multi-part question... use deep_research'). It also lists trigger phrases and examples.

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

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

Discloses that candidate routing improvements may be enabled live during tests, that no candidate is currently active, and that the tool is a full working router with no fallback—not a stub. This adds important behavioral context beyond the read-only, idempotent annotations, revealing its experimental and potentially changing behavior.

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

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

The description is front-loaded with the core identity ('Beta version of ask_pipeworx') and every sentence adds functional value: identical behavior, current state, usage instruction, and fallback reassurance. It is slightly verbose but remains efficient and well-structured.

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

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

The description covers the tool's purpose, relationship to the stable version, current status, and usage. It does not elaborate on the response shape, but it explicitly states it is the same as ask_pipeworx, which suffices given the reference to the sibling and the lack of an output schema.

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

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

The input schema already documents the 'question' parameter and all five aliases with 100% coverage. The description only references 'same arguments' without adding new semantic detail, so it does not improve upon the schema's own parameter descriptions.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, an identical universal router with the same 5,521 tools, arguments, and response shape. It distinguishes itself from the stable ask_pipeworx by being the experimental edge with candidate routing improvements.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes results are compared against the stable router to decide merges. This gives clear when-to-use guidance and names the alternative (ask_pipeworx).

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive, but the description goes beyond by detailing the exact return structure (answer, evidence, confidence, source, fetched_at, refusal_reason:null) and explicit refusal reasons (not_in_source, no_tool_match, tool_error, data_truncated, llm_error). It also explains that it extracts using ONLY the tool result, which is critical behavioral context. No contradiction.

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

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

The description is dense but every sentence serves a purpose: definition, mechanism, return contract, refusal cases, use cases, cost comparison, and alternative. It is front-loaded with the core concept and structured logically. No fluff.

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

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

Given the tool's complexity, the description covers everything an agent needs: purpose, behavior, return format, refusal semantics, use cases, exclusions, cost, and relation to sibling. The input schema is simple (one param) and annotations are strong, so the description fully compensates for lack of output schema by detailing the return structure.

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

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

Schema description coverage is 100% — the single required parameter 'question' and all aliases are fully described in the schema. The description does not add additional parameter semantics beyond that, which is acceptable. Per baseline rule for high coverage, score 3.

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

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

The description clearly states this is a 'hallucination-resistant answer mode' that extracts answers using only tool results, with a refusal mechanism. It explicitly distinguishes from sibling tool ask_pipeworx by noting same routing but grounded extraction, and from other siblings by specifying high-stakes uses. Verb+resource+scope is specific and unique.

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

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

Provides explicit when-to-use guidance: 'Use whenever an answer will be quoted, cited, or acted on...' and when-not-to-use: 'prefer ask_pipeworx for casual lookups.' It also names the alternative (ask_pipeworx) and explains the cost tradeoff. This is excellent actionable 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?

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, the description goes far beyond them. It discloses resolver contract (market_match_confidence), safety short-circuits ('low_confidence_match', 'market_closed_or_inactive'), illiquidity handling, news fallback mechanisms, and cancellation-rule risk. No contradictions with annotations.

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

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

The description is very long but structured with clear section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, etc.) and front-loaded with purpose. Every section adds value, though its length is substantial. It balances detail with organization, so it earns a 4 rather than 3.

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 return values and behavior. It does so comprehensively: response shapes (result.market, result.analysis, result.evidence), resolver contract, parent_event extractor, news fields, safety statuses, and resolution-rule risk. For a complex tool, this is exceptionally complete.

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

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

The input schema covers 100% of parameters with detailed descriptions for market, depth, and include_raw. The description adds some context for market input formats (slug, URL, question text) and mentions fan-out behavior, but it does not significantly enrich parameter understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly explains the tool's core function (resolve, classify, fan out, return evidence) and distinguishes it from sibling tools such as polymarket_arbitrage or ask_pipeworx by emphasizing the data-fan-out research behavior.

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

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

Explicit usage contexts are given: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' This clarifies when to invoke the tool. However, it does not directly name alternative tools or state when not to use this tool, so it misses a bit on 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?

Beyond the annotations (readOnly, idempotent, etc.), the description discloses concrete behaviors: pulls 10-K data from SEC EDGAR/XBRL for companies, handles off-calendar fiscal years, retrieves FAERS/FDA/trial counts for drugs, sorts by primary metric, and returns citation URIs. This is rich, useful context that annotations alone do not provide.

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

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

The description is concise but information-dense, with every sentence contributing new value: trigger phrases, data sources, fiscal-year handling, sorting, and return format. The opening phrase immediately anchors the tool's purpose, and the length is justified by the tool's complexity.

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

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

Given the tool's complexity (two entity types, multiple data sources, sorting, citations), the description covers all critical aspects: what it does, when to use it, what data it retrieves, how results are ordered, and what the output includes. No output schema exists, so the description carries the burden, and it does so thoroughly.

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

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

While the schema already covers both parameters, the description adds meaningful semantics: it explains what 'type' controls (company vs drug data sources) and what the 'values' array should contain for each type, with concrete examples. The schema_description_coverage is 100%, but the description goes beyond the schema by clarifying the data pulled and the sorting behavior.

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: side-by-side comparison of 2–5 companies or drugs in a single parallel call. It explicitly contrasts with sequential single-pack lookups and includes trigger phrases ('X vs Y', 'which is bigger'), making it easy for an agent to recognize when to invoke it.

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

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

The description gives explicit when-to-use guidance via trigger examples and an 'ALWAYS PREFER' directive over sequential lookups. It also differentiates between company and drug modes, describing the data sources and metrics for each, so the agent knows exactly when this tool is the alternative to other 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?

Goes far beyond the readOnly/openWorld/idempotent annotations. Discloses account/paywall requirements, parallel execution, output format (findings packet with verbatim evidence, confidence, source, fetched_at, citation_uri), explicit gaps[] for unanswered facets, contradictions[] in standard/thorough, and latency expectations. Also clarifies that citations are only returned when resolvable and that records are semantically excerpted.

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 intentionally dense. Every sentence carries unique information and the most critical caveats (account required, alternatives) are front-loaded. However, it is a run-on wall of text without paragraph breaks or bullet points, which makes it less scannable than ideal for an agent needing quick reference.

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 covers all necessary aspects: prerequisites, alternatives, input semantics, output structure, edge cases (empty gaps, unresolvable citations), performance latency, and depth-specific behavior. It even explains how it avoids hallucination ('never invented') and how large records are handled. Nothing important seems missing.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds meaningful nuance: depth is tied to number of facets, hop behavior, gap recovery, and contradiction scanning; question is described as 'Broad/multi-part is fine — decomposition is the point'. This goes beyond the schema's terse descriptions, though it doesn't provide concrete formatting examples.

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

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

The description clearly states the tool performs 'Grounded multi-source research across Pipeworx's 1452 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,521 tools IN PARALLEL'. It uses a specific verb+resource and explicitly distinguishes itself from open-web search and sibling tools like 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?

Provides explicit when-to-use and when-not-to-use guidance: requires a sign-in and paid plan for 'thorough' depth; says to use ask_pipeworx if not signed in, for single lookups, or for breaking/current-news topics. Also explains the depth tiers' iterative behavior so users know which depth to pick.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so safety is covered. The description adds valuable behavioral context: returns top-N results with names, descriptions, full input schemas, and curated examples, and results are directly callable without a second lookup. It also advises calling this first for broad exploration. This goes beyond the annotations and enriches the agent's understanding of the tool's behavior.

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

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

The description is three sentences, front-loaded with the primary purpose, and every sentence earns its place. It lists relevant domains efficiently, explains the return format and the 'call first' advice. There is zero fluff, and the structure is logical: purpose → when to use → what you get.

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 6 parameters (with 5 aliases), 100% schema coverage, and no output schema. The description adequately explains what the tool returns (top-N tools with schemas and examples) and gives context for the alias system. It covers the discovery purpose and the direct-callability advantage, making it sufficiently complete for the agent to use correctly without additional details.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by providing concrete examples ('look up FDA drug approvals', 'analyze housing market trends') and explicitly mentions that the query parameter accepts aliases (task, q, description, search), which clarifies the intended usage. It also reinforces the limit parameter with 'top-N'. This adds value beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Find tools by describing the data or task.' It uses a specific verb ('find') and resource ('tools'), and distinguishes itself from sibling tools by emphasizing discovery across many domains (SEC filings, FDA drugs, etc.) and noting the output includes schemas and examples. This makes its role as a meta-search/discovery tool 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: 'Use when you need to browse, search, look up, or discover what tools exist for...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' It does not explicitly name alternative tools to use instead, but the 'not just one answer' phrasing implies the tool is for exploring options rather than retrieving a single result. This is clear enough to guide the agent.

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 readOnlyHint=true, the description discloses important behaviors: the patent API is sunsetting with 'soft-fails until reactivated', and it fans out in a single parallel call across multiple sources. This adds valuable context not available from annotations alone.

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

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

Although the description is a single dense paragraph, each sentence earns its place: example queries, preference guidance, fan-out details, return fields, and input constraints. 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?

With no output schema, the description enumerates the exact return fields (cik, company_name, recent_filings, fundamentals, patents, news, LEI) and specifies data provenance, ordering, and failure modes. It is fully self-contained 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?

The schema already documents both parameters with full descriptions, including examples 'AAPL' and '0000320193' and the note about names not being supported. The description repeats this information without adding new semantics, so the baseline of 3 applies.

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

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

The description clearly states it 'full cross-source profile of a US public company in ONE parallel call' and lists concrete return fields. It distinguishes from alternatives with 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and from sibling tools like resolve_entity.

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

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

Provides explicit usage guidance with 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and tells users to use resolve_entity if they only have a name. This clearly indicates when to use the tool versus alternatives.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows it is a destructive, idempotent operation. The description adds useful context about clearing sensitive data and targeting previously stored memories, going beyond the annotations without contradicting them.

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

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

The description is three sentences, front-loaded with the core action, followed by usage guidance and related tools. Every sentence adds value with no redundancy or fluff.

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

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

For a simple single-parameter tool with no output schema, the description covers purpose, usage, and related tools. Annotations handle safety traits (destructive, idempotent), and the schema documents the parameter, making the description sufficiently complete.

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

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

Schema coverage is 100% with a clear description for the key parameter ('Memory key to delete'). The tool description repeats 'by key' but does not add extra detail such as key format, case sensitivity, or typical examples, so it does not enhance the schema's meaning.

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

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

The description clearly states the tool deletes a previously stored memory by key, using a specific verb (delete) and resource (memory). It differentiates from siblings like remember and recall by explicitly pairing with them, making its role in the memory API 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 conditions for use: when context is stale, task is done, or to clear sensitive data. It also mentions pairing with remember and recall, indicating complementary tools and when to use them instead.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive hints. The description adds that it fetches the page, extracts specific elements, and emits a text blob in standard llms.txt markdown, giving useful behavioral context beyond annotations.

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

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

Three sentences, front-loaded with the main action, then process details, then practical use cases. Every sentence provides value without redundancy.

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

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

Despite no output schema, the description states the output is a single text blob in standard llms.txt markdown, ready to be dropped at site-root. It covers purpose, process, and output, and the schema covers parameters, making it complete for this tool.

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

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

Schema covers 100% of parameters with clear descriptions, including defaults for max_links. The description adds context by mentioning 'any URL' and the extraction of title/description/key links, but doesn't add detail beyond the schema for individual parameters.

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

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

The description uses the specific verb 'Generate' with resource 'llms.txt file for any URL' and details the process (fetches, extracts, emits), making it distinct from siblings like ai_visibility_check. It clearly states the tool's output and 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 lists three use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing a competitor's AI visibility. This gives clear when-to-use guidance, though it doesn't mention alternatives or when-not-to-use.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the bar is lower. The description adds meaningful behavioral details beyond that: it only reads from *PUBLIC* repositories, returns decoded text capped at ~60k, and provides a directory listing with {name, path, type, size} when the path is a directory. This is useful context not covered by annotations.

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

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

The description is three sentences, front-loaded with the main action, followed by usage guidance and parameter instructions. Every sentence is purposeful and there is no redundancy or filler. It is concise yet informative.

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

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

Despite lacking an output schema, the description sufficiently explains the return values: decoded text for files (with a ~60k cap) and directory listings with specific fields. It covers the main use cases, outlines public repo restriction, and distinguishes this tool from siblings like search_code and web search. Error behavior is not critical for this simple read operation, so the description is complete enough.

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 does not add much beyond the schema: it repeats the 'omit path for root' and 'ref is branch/tag/SHA' details already in the schema. It does note the return format (decoded text vs. directory listing), which is slightly useful, but it does not meaningfully enhance parameter understanding.

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

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

The description explicitly states the tool's function: 'Read a file from a PUBLIC GitHub repository (or list a directory) by path.' It uses a specific verb and resource, and distinguishes itself from web search and sibling tools by focusing on reading file contents from a repository path.

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

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

The description provides explicit guidance on when to prefer this tool: 'PREFER OVER WEB SEARCH for "show me the README / package.json / <file> of <repo>"' and includes concrete scenarios like inspecting source/config files. It also clarifies how to pass owner, repo, and path, and the optional ref parameter, making usage conditions clear.

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

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

The description goes beyond the readOnlyHint annotation by detailing what data is returned: latest stable release (with tag, name, date, prerelease flag, release notes, assets with download counts) plus recent releases. It also discloses an important behavioral edge case: fallback to git tags when formal releases do not exist. This adds significant transparency beyond the annotations.

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

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

The description is two sentences, tightly packed with relevant information. It front-loads the core purpose, then expands on return values and fallback behavior. No filler or redundancy; every clause contributes meaning.

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

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

Given the tool has 3 parameters, no output schema, and strong annotations, the description fully compensates by explaining the return contents, the fallback behavior, and the intended use cases. It is self-contained and provides enough context for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so parameters (owner, repo, per_page) are already fully described. The description adds only marginal semantic value by mentioning 'recent release history' which implicitly relates to per_page, but it does not elaborate on parameter syntax or specifics 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 identifies the tool's purpose: retrieving the latest release and release history for a repository. It uses a specific verb ('Get'), names the resource ('releases'), and provides concrete example questions it answers ('what is the latest version', 'when was last released', 'what changed'), making it distinct from sibling tools like get_repo or get_file_contents.

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 context: it is the 'canonical way' to answer release-related questions and mentions fallback behavior for repositories that only use git tags. It does not explicitly name alternative tools, but the use cases are clearly scoped, and the fallback note helps decide when this tool is still appropriate.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive. The description adds context by specifying the tool handles exactly one repo and enumerates the returned data fields, which is useful beyond annotations.

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

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

Two well-structured sentences front-load the core purpose and usage. Every clause adds value: the examples clarify input format, and the listed outputs set expectations.

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 lookup tool with a rich output schema and strong annotations, the description covers purpose, input format, usage timing, and expected data. No critical gaps remain.

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

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

Schema description coverage is 100%, and the schema already documents that repo accepts full slug and owner may be omitted. The description repeats this information without adding new semantic detail 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 looks up ONE named repository by its owner/repo slug, with specific examples like 'facebook/react'. It identifies the exact resource and distinguishes from search_repos by emphasizing 'named' vs 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?

The description provides an explicit when-to-use: 'Use this whenever the repository is named in the question.' It does not explicitly mention alternatives or when-not-to-use, but the context is clear and adequate.

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 the specific fields returned and an example of the username parameter, which is context beyond annotations.

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

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

The description is a concise two-sentence structure that front-loads the purpose, lists key return data, and gives a usage example. Every sentence adds value.

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

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

With a rich output schema, detailed annotations, and a single well-documented parameter, the description is sufficient. It covers the essential purpose, return fields, and parameter example, leaving no ambiguity.

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

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

Schema already describes the username parameter with a GitHub username example and covers 100% of parameters. The description's example ('username="torvalds"') mirrors the schema, adding no new semantics beyond what's already documented.

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

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

The description explicitly states 'Get a GitHub user's public profile info' with a list of returned fields, clearly specifying the verb, resource, and scope. This distinguishes it from siblings like get_repo or get_releases.

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

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

The description provides clear context on when to use this tool—when a GitHub user's public profile is needed. It doesn't explicitly name alternatives, but the purpose is unambiguous, and no exclusions are needed.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, so the bar is lower. The description adds valuable context by revealing that it is computed live from the GitHub Search API, that ordering differs from github.com/trending due to an unpublished algorithm, and that every response includes a caveat field. This goes 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 well-structured and front-loaded with the core purpose, then expands into modes, parameters, and the caveat. It is mildly verbose with the list of example questions and some repetitive phrasing, but every section earns its place given 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 takes on the burden of explaining return values and does so explicitly by listing full_name, description, language, stars, forks, dates, topics, and URL. It also covers the live computation and the caveat field, making it complete for a six-parameter, mode-based tool.

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

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

Schema coverage is 100%, so the baseline is 3. The description significantly enriches parameter understanding, particularly for mode (explaining the nuanced difference between creation and push windows) and min_stars (noting its value with mode='active'). It also clarifies query as free-text, going beyond the terse schema descriptions.

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

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

The description clearly identifies the tool as listing trending GitHub repositories, with vivid example queries and a clear distinction from github.com/trending. It goes beyond a generic verb+resource by detailing two modes and their semantics, setting it apart from sibling search 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 explains when to use each mode (new for 'what blew up this week', active for 'established projects under heavy development') and gives practical guidance on setting since, language, query, and min_stars. It does not explicitly name alternative tools like search_repos, so it misses the 'when-not-to-use' component for a 5.

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

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

Annotations already declare readOnly, idempotent, and openWorld hints. The description adds useful behavioral context by stating that it returns sha, message, author, and date per commit, and explains the optional filters. This goes beyond the basic safety profile without contradicting 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 three sentences, tightly packed with purpose, usage guidance, parameter hints, and return details. Every sentence earns its place, and it is front-loaded with the core purpose.

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

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

For a read-only commit listing tool with no output schema, the description covers the key elements: what it does, when to use it, key parameters, and return fields. It doesn't explicitly state sorting order or pagination defaults, but the schema already documents per_page, and 'recent' implies recency. Slight ambiguity about ordering prevents a perfect score.

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 semantic value by clarifying that 'sha' is a branch/tag/commit to start history from, 'path' limits to commits touching a file/dir, and since/until are ISO timestamps. This complements the schema with more intuitive explanations.

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

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

The description clearly states the tool lists recent commits on a repository to show latest activity, what changed, and who is committing. It uses a specific verb and resource, and explicitly contrasts with web search, which helps distinguish it from alternative approaches like web search or other repo 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 'PREFER OVER WEB SEARCH' for specific query types, providing direct guidance on when to use this tool. It also outlines optional parameters that refine usage, making the intended context very clear.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond those annotations: it states that pull requests are filtered out automatically and that the default state is 'open'. These are useful details not present in the annotations, so the description adds value 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 two concise sentences with front-loaded information. It states the purpose first, then adds the PR filter and return fields, and finally the default. Every word earns its place, with no redundancy or fluff.

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

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

The tool has a simple operation with clear scope, defaults, and return fields listed. The schema handles parameter boundaries, and the description covers the behavioral nuance (PR filtering). Some might argue that pagination or sorting isn't mentioned, but per_page is already in the schema and the default open state is stated. This is complete enough 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?

The input schema covers 100% of parameters, including descriptions for state and per_page. The description reinforces owner/repo naming and the default state, but it doesn't add any new semantics or clarify parameter formats beyond what the schema already provides. Therefore, a 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 a specific verb ('List'), the resource ('issues for a GitHub repository'), and the key scoping parameters (owner and repo name). It also distinguishes itself from related tools by explicitly noting that pull requests are filtered out automatically, which is a unique behavioral detail beyond a generic '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 implies when to use the tool: when you need issues for a specific repo, with a default to open issues. It mentions the repository scoping (owner/repo) and the automatic PR filtering, which guide usage. However, no explicit alternatives are named, and there is no 'when not to use' guidance, so it falls short of a 4.

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

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

Annotations already declare this as readOnly, idempotent, and non-destructive. The description adds useful behavioral context by specifying the return fields (id, type, params, etc.) and clarifying that only active subscriptions are listed by default, complementing the annotation coverage.

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

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

The description is two sentences, front-loaded with the primary purpose, and every sentence adds value: the first states what it does and what it returns, the second gives practical use cases. No wasted words.

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

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

Given the tool's simplicity (one optional parameter, read-only), the description is fully complete: it lists the return fields, notes the default active filter, and provides usage guidance. With strong annotations and schema coverage, no further context 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 schema fully documents the single optional parameter `include_inactive` with a clear description, so the description doesn't need to add much. It does implicitly clarify the default behavior by saying 'active subscriptions,' which aligns with the schema's default false. Baseline 3 is appropriate 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 tool's function: 'List the caller's active subscriptions.' It uses a specific verb and resource, and distinguishes itself from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions.

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

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

The description explicitly explains when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context and implies alternatives (subscribe to add, unsubscribe to cancel), making it easy for an agent to select the right 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 are all false and offer no safety or behavioral context, so the description carries the full burden. It discloses the claim_token workflow, rate limiting (5/day), free usage, daily digest review by the team, and the consequence of misreporting (delays). This goes well beyond the bare annotations.

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

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

The description is long but every sentence contributes: purpose, when-to-use, scope exclusions, token workflow, roadmap impact, rate limit, and quota. It is logically ordered and front-loaded with the core action. No filler.

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

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

Given the tool's complexity (4 params, nested object, enum, optional params, token-based follow-up workflow) and the lack of output schema/beneficial annotations, the description covers all critical aspects: usage conditions, parameter handling, return token semantics, and operational limits. It is fully self-sufficient.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical meaning by explaining the claim_token lifecycle ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifying content constraints ('don't paste the end-user's prompt'), and providing examples of pack/tool names in context, which the schema does not.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes this from sibling tools by scoping it to feedback for Pipeworx-served tools and enumerating feedback types (bug, feature/data_gap, praise).

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

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

Provides explicit when-to-use conditions for each feedback type and a clear when-not-to-use rule for tools from other MCP servers, directing users to file with that server instead. It also clarifies how to identify Pipeworx tools, offering a complete alternative/exclusion set.

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 and idempotent, but the description adds context: data provenance ('derived from CF analytics-engine'), privacy ('no PII'), and caching ('Cached 5min-1h'). This goes beyond the structured hints.

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—two sentences plus a numbered list—and every sentence adds value: definition, use cases, data source/caching. It is front-loaded with the core function.

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

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

Despite no output schema, the description specifies the return content ('top tools, top packs, total call volume', 'pack, tool, count') and explains the window behavior. Caching and use cases round it out. The tool's simplicity (1 optional param) allows this to be sufficient.

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

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

The input schema already covers the single `window` parameter with a full description, and the tool description also mentions the window options in the first sentence. Per the rubric, high schema coverage yields a baseline of 3; the description contributes no additional parameter semantics.

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

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

The description uses a specific verb ('Returns') and identifies the exact resource ('the top tools, top packs, and total call volume') plus the window options. It clearly distinguishes from siblings like discover_tools by focusing on current usage trends among 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?

It provides three explicit 'Useful for' scenarios, telling agents when to invoke it—discovering hot data sources, confirming canonical tool choice, and checking alignment. It does not name alternatives or explicitly state when not to use it, so it falls slightly short of a 5.

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

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

While annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description reveals internal behaviors beyond safety: threshold deviations >3pp, Jaccard similarity ≥0.30, placeholder fraction >20%, and fill check against live CLOB depth. It clearly explains the meaning of realizable_edge_pp ≤ 0 and its trading implication. This is rich behavioral context.

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

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

Though lengthy, the description is efficiently structured with uppercase section labels (SEMANTIC ANCHOR, PARTITION FILTER, RESPONSE, FILL CHECK). Key usage instructions appear up front. Every sentence adds distinct value—there is no redundancy or fluff. The length is commensurate with 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?

The tool has no output schema, but the description fully specifies the response fields (opportunities[], partition_check, fill_check) and explains edge cases like skipped_low_similarity, placeholders_filtered, and thin_legs. It also cross-references polymarket_fill_risk for sizing. For a complex, two-mode arbitrage tool, the description is complete.

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

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

Schema description coverage is 100% for both params, but the description adds significant semantics beyond the schema. It explains event slug examples, accepts full URLs, differentiates topic vs event behavior, and details the output for each mode. The description makes the parameter roles far clearer than the schema alone.

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

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

The description opens with a specific verb and resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_fill_risk, and even references polymarket_fill_risk as an alternative. The scope is 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?

Usage guidance is explicit and actionable: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', and 'topic (for cross-event scanning)'. It describes when to choose each mode, mentions the alternative tool for custom sizing, and warns not to trade when realizable_edge_pp ≤ 0. This is textbook when-to-use guidance.

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

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

The description discloses extensive behavioral details beyond the annotations: caching ('Cached 1h at the KV level'), model family logic, Kelly fraction capping, slippage handling, placeholder-slug filters, and a 24h-move warning. It also explains why some opportunities are excluded (fed bets) and provides a _diagnostics section so callers can understand empty results. Annotations already declare read-only/idempotent, but the description adds substantial 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 very long and dense, with nearly 100 words of detail including model families, response structure, and diagnostics. While it is organized with section-like labels (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, etc.), it could be more concise. The length is justified by the tool's complexity, but it is not 'front-loaded' beyond the opening sentence and includes details that could be left to an output schema or documentation.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It explains the response top-level structure (by_segment, fed_candidates, _diagnostics), field semantics (edge_pp_net, kelly_fraction, liquidity, spread_pp), and edge cases (placeholder slugs, stale market handling). It also covers the caching behavior and why certain segments might be empty. The description adequately prepares an agent to interpret and invoke the tool.

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

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

With schema coverage at 100%, the baseline is 3. The description adds value by explaining parameter semantics in context, e.g., min_partition_leg_kelly clarifies why min_kelly doesn't apply to partition arbs, and tradeable-edge knobs (min_liquidity/max_spread_pp) are described as filters for realizable edges. It also provides real-world slippage context ('Polymarket has zero trading fees... bid/ask typically eats 20-50bp'). This goes beyond the schema descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also names the intended use case ('what should I bet on today'), but it does not explicitly differentiate from sibling tools like polymarket_arbitrage or polymarket_edge_tracker. The verb+resource is specific, but sibling distinction is missing.

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: 'Built for what should I bet on today — agents discover opportunities without paging hundreds of markets.' It also explains when not to use certain features (e.g., fed bets are excluded due to unreliable signals), implying when to avoid those. However, it does not explicitly name alternative tools or state 'use this instead of X', so it lacks explicit exclusions/alternatives.

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

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

Beyond the readOnly/idempotent annotations, the description discloses detailed behavioral traits: response structure (tracked, expired, snapshot_dates), the meaning of negative edge values ('negative = SELL YES'), the 60-day snapshot TTL limit, and that decay numbers come from daily closes, not intraday. 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 lengthy but well-structured into sections (purpose, args, response, limits). Every sentence carries meaningful information, though it could be slightly more compact without losing value.

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

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

With no output schema, the description fully documents the response fields (tracked, expired, snapshot_dates) and their semantic meaning, including edge cases like missing snapshot days and TTL constraints. It is highly complete for a read-only telemetry tool with moderate 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% for both parameters, so the baseline is 3. The description adds context beyond the schema by explaining 'days' as a lookback and 'window' as a snapshot family, and clarifies the default window. This additional meaning justifies a 4.

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

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

The description explicitly states the tool's purpose: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers the specific question 'how long has this edge existed and is it shrinking?'. This clearly distinguishes it from siblings like polymarket_edges which likely provides current edges.

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

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

The description implies when to use it—when edge persistence/decay matters, contrasting fresh vs old edges—but does not explicitly name alternative tools or state exclusions. The clear use case is present, but it lacks explicit 'when not to use' guidance.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which already establish a safe read operation. The description adds rich behavioral context: it walks the order-book ladder, returns specific metrics (top_of_book, vwap_fill_price, slippage_pp, verdict), explains mode-specific behavior, and warns about partial fills converting arbs into directional risk. This far exceeds the annotation baseline.

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 long, dense paragraph but every sentence contributes meaningful information: modes, parameters, return fields, risk warnings, and usage context. It is not padded, though a bulleted structure would improve readability. Slight deduction for length forcing the agent to parse a wall of text.

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

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

For a complex two-mode tool with no output schema, the description is remarkably complete. It enumerates return fields for both modes (top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict; theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs, forced_directional_risk), explains edge cases, and ties usage to sibling tools. Nothing critical is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description significantly enriches parameter semantics. It explains the side parameter with mode-specific values (buy_yes|sell_yes|buy_no|sell_no for single-market, sell_yes/buy_yes for basket, auto default), clarifies size_usd interpretation (max spend on buys, target proceeds on sells, settlement notional for basket), and defines market/event modes explicitly.

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

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

The description explicitly states it performs an 'edge check against live CLOB order-book depth' with a specific verb and resource. It clearly distinguishes between single-market and basket modes and references sibling tools (polymarket_arbitrage, polymarket_edges), making its 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?

It gives explicit usage 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 the tool is necessary (theoretical overround on thin books is not capturable) and the risk of not using it (partial basket fills turn arb into unhedged directional position).

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses substantial behavioral nuance: compatibility_warning conditions (matched_pairs:0 with skipped_cross_type>0 vs both venues >5 legs), temporal_alignment implications ('aligned:false means spreads are mathematically meaningless'), and skipped_cross_type/subtype counters. It also warns about the gap between pre-mapped and tradeable. No contradiction with annotations; the description adds value well beyond what 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?

The description is dense and long, but every sentence contributes meaningful information: purpose, modes, response format, safety fields, temporal alignment, and a caveat. It is front-loaded with the core purpose and then expands into structured details. A slightly more structured layout (e.g., bullet points) would improve readability, but the text is not padding or redundant; it earns its length 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?

There is no output schema, so the description carries the full burden of explaining the return values. It explicitly describes the response: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp (Kalshi − Polymarket)', and covers the safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). For a 3-parameter tool with two modes and complex return semantics, the description is complete and self-sufficient.

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

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

Schema coverage is 100%, and the description adds semantics above the schema's property descriptions. It explains the mode distinction ('topic' vs explicit overrides) and how explicit parameters override the topic-mapped side. The schema already lists the topic enumeration and provides examples, but the description connects them to the two modes and clarifies that explicit parameters override the mapped side in a way not explicitly stated in the schema's property text. This goes slightly beyond the baseline for full 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 a clear statement of purpose: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It specifies the resource (Kalshi/Polymarket), the action (comparing/spread), and the scope (same resolving question). It also distinguishes itself from siblings like polymarket_arbitrage by emphasizing cross-venue rather than intra-venue, and the two modes (topic shortcuts vs explicit tickers) further clarify exactly what it 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 gives explicit when-to-use guidance via two modes ('TWO MODES: (1) topic — 10 pre-mapped macro shortcuts... (2) explicit kalshi_event_ticker + polymarket_event_slug'), and warns when not to trust results ('Real cross-venue spreads are rarer than the macro-shortcut list suggests — most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable'). However, it does not name specific sibling tools as alternatives, so it lacks the explicit exclusion/alternative naming that would merit a 5.

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

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

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds behavioral context beyond annotations by noting scoping to the user's identifier (anonymous IP, BYO key hash, or account ID) and the ability to list all keys when the key argument is omitted. This enriches the 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?

The description is two sentences, front-loaded with the primary action, and every clause adds value. No redundancy or filler. It efficiently conveys purpose, usage, scoping, and sibling relationships.

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

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

For a simple tool with one optional parameter, no output schema, and strong annotations, the description covers all essential aspects: what it does, when to use it, scoping, and pairing with remember/forget. It omits the exact return format, but for a memory retrieval tool this is adequately inferred from the stated behavior.

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

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

Schema coverage is 100% with a clear description of the single 'key' parameter. The tool description adds meaning by giving concrete examples of key content (user's target ticker, address, research notes) and clarifying that keys are saved via remember, which goes beyond the schema's basic 'Memory key to retrieve'.

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 two main actions: retrieving a saved value and listing all keys, using specific verbs and a clear resource (previously saved memory). It also differentiates from sibling tools by explicitly pairing with remember and forget, 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 guidance on when to use the tool: to look up context stored earlier (ticker, address, research notes) without re-deriving it. It also names alternatives (remember to save, forget to delete), giving clear context on when to use this tool versus its siblings.

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

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

The description discloses mark_read:true as a state-changing operation ('flag returned events read so the next call only shows newer ones'), contradicting the readOnlyHint:true annotation. Per rubric, this is an annotation contradiction, so the score is 1 despite the description's other useful behavioral details.

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

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

The description is front-loaded with the main action, then flows logically through return format, filtering, state mutation, and polling. Every sentence adds distinct information with no fluff or repetition.

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

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

Despite lacking an output schema, the description explains what returned alerts contain (source, citation_uri, raw payload). Combined with full schema coverage for parameters and relevant annotations, the tool is well understood. It misses explicit mention of limit/unread_only, but the schema covers those.

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?

With 100% schema coverage, the baseline is 3. The description adds value by providing a concrete type example ('sec_8k'), clarifying that since is an ISO timestamp, and explaining the mark_read side effect, going beyond the schema descriptions.

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

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

The description opens with 'Pull fired events from your subscription feed,' clearly identifying the action and resource. It further specifies the scope ('most recent alerts'), distinguishing it from sibling tools like list_subscriptions and 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 concrete usage context: filtering by type and since, setting mark_read, and polling. It also points to an alternative endpoint for scripts/dashboards, which helps with tool selection, though it doesn't explicitly name sibling tools to avoid.

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 read-only/idempotent annotations, the description discloses concrete behavior: parallel fan-out across sources, GDELT-to-GNews fallback on rate limits or 5xx, and USPTO soft-failure due to the PatentsView API sunset. It also describes the return structure (changes[] grouped by source, total_changes, citation URIs), which is valuable behavioral context.

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

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

The description is dense and front-loaded with user intents, and every clause adds meaningful information. It is a single run-on paragraph rather than scannable bullets, but for the tool's complexity it remains appropriately sized with no filler.

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

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

With no output schema, the description takes responsibility for explaining return values, which it does at a high level (structured changes[] grouped by source, total count, citation URIs). It also covers source behavior and fallbacks. It doesn't detail the exact change object fields or pagination, but for selection purposes it is sufficiently complete.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving concrete `since` examples ('7d', '30d', '3m', '1y') and a recommended default ('30d' or '1m' for typical monitoring), plus user-intent examples that map to the `value` parameter. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states this is a change feed for a company over a recent window, with specific verbs ('What's new', 'latest', 'updates') and resources (SEC EDGAR, GDELT/GNews, USPTO). It distinguishes itself from entity_profile by explicitly noting the static profile 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 opens with natural-language query examples that signal when to use the tool, and explicitly directs users to entity_profile when a static profile is needed regardless of window. This provides a clear alternative and contextual selection guidance.

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

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

Beyond the annotations, the description discloses important behavior: memory is scoped by the agent identifier, authenticated users get persistent memory, and anonymous sessions retain it for 24 hours. It also frames the tool as a storage operation paired with recall/forget, adding meaningful context beyond 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?

Three focused sentences, front-loaded with the core action, followed by usage guidance, storage details, and companion-tool references. No filler or redundant restatement of the tool name.

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 memory tool, the description covers purpose, when to use it, persistence semantics, scoping, and related tools. Combined with helpful annotations, the description is complete enough for an agent to select and invoke it correctly.

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

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

The input schema already describes both parameters fully (100% coverage), including key and value format examples. The description reinforces that the tool stores key-value pairs but does not add further parameter-level details 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 opens with 'Save data the agent will need to reuse later', giving a specific verb and resource. It also explains the key-value storage model and explicitly mentions recall and forget, which distinguishes it from sibling retrieval/deletion 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 provides clear usage context: 'Use when you discover something worth carrying forward' and gives concrete examples. It names recall and forget as complementary tools, but does not explicitly state when not to use remember.

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, covering the safety profile. The description adds meaningful behavioral context: each call cascades through multiple lookup endpoints, uses auto-disambiguation for companies, and returns specific citation URIs (pipeworx://edgar/company/{cik}, pipeworx://rxnorm/concept/{rxcui}). No contradiction with annotations.

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

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

The description is well-structured with a quoted example intro, a clear purpose statement, and a 'SUPPORTED TYPES' section. It is slightly longer than necessary but every sentence adds useful information. The use of examples and parenthetical details is 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?

Given that there is no output schema, the description fully covers what the tool returns for each entity type (ticker, CIK, company name, citation URI for companies; RxCUI, ingredient, brand, citation URI for drugs). It also explains input flexibility and the cascading lookup behavior, so the agent has enough context to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema by providing concrete examples for each parameter (e.g., 'AAPL', '0000320193', 'ozempic') and explaining what each entity type returns, which helps the agent construct valid invocations.

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 that the tool resolves user-spoken entity names to canonical/official identifiers. It provides concrete example queries and specifies the supported types (company, drug), distinguishing it from sibling tools like entity_profile or compare_entities by framing it as the tool to 'use FIRST' when you have a name but need an ID.

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

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

The description gives explicit usage guidance: 'Use FIRST whenever you have a name but need an ID.' It also details what input formats are accepted for each entity type and mentions that using it replaces 2-3 manual lookups. However, it does not explicitly discuss when not to use the tool or mention alternative sibling tools for specific scenarios.

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive behavior. The description adds meaningful behavioral context beyond these: it explains the tool probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with specific metrics (score, confidence, signal density). It also adds nuance about model selection and API key requirements, which is valuable for understanding side effects and dependencies.

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-loaded: the first sentence states the core function, the second explains the mechanism, the third gives a use case, and the fourth lists the returns. Every sentence adds value, with no fluff or repetition. It is tightly written and appropriately sized 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?

There is no output schema, so the description must explain return values, which it does: 'Returns ranked list with score, confidence, signal density per entity.' It also covers the use case, the probing mechanism, and parameter nuances like model selection and shared context. Given the moderate complexity and strong annotations/schema, the description is sufficiently complete for an agent to invoke and interpret the tool.

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

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

Schema coverage is 100%, so the baseline is 3. The tool description adds some contextual meaning (e.g., 'your brand + N competitors' aligns with the schema's first-entity-as-subject note), but it largely repeats what the schema already documents. The description does not add significant new parameter-level semantics beyond the schema, so it stays at the baseline.

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

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

The description clearly states the tool's function: 'Compare AI visibility across multiple entities side-by-side.' It uses a specific verb ('Compare') and resource ('AI visibility'), and distinguishes itself from siblings by explicitly mentioning it probes with ai_visibility_check and ranks results, which is a unique feature among the listed siblings.

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

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

The description provides clear context for when to use the tool: 'Useful for competitive AI-marketing audits' with an example query. It implies the multi-entity comparison use case but does not explicitly exclude alternatives like using ai_visibility_check for single entities or compare_entities for general comparisons. It gives good contextual guidance but lacks explicit 'when not to use' statements.

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 valuable context beyond that: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30 seconds and may time out, and 'sources_failed' will be included in that case while the rest still returns. This latency and degradation behavior is exactly the kind of context that helps an agent set expectations and handle errors.

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 efficient: it leads with the primary purpose, then gives usage triggers, a detailed return summary, ecosystem scope, and failure behavior. Each sentence contributes meaningful information, though the length is on the higher side; still, it 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?

With no output schema, the description fully enumerates the return structure (summary block fields like is_latest, license, bundle_kb_min/gz, dependency_count, etc.), per-advisory detail, links, and recent alternative versions. It also covers edge cases like timeouts and partial failures, making it complete for the complexity of this multi-source tool.

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

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

The input schema already provides 100% coverage, describing package as an npm package name (with scoped packages accepted) and version as a specific version with a default of latest. The description does not add significant new meaning to the parameters beyond what is in the schema, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite 'should I add this npm package' check combining deps.dev and bundlephobia data. It distinguishes itself from siblings by explicitly naming the data sources and the specific question it answers, and by contrasting with direct deps.dev:version usage 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?

The description explicitly tells agents when to use it: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me".' It also provides an alternative for non-NPM ecosystems, stating 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly,' which is clear guidance on when not to use this tool.

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

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

The description adds behavioral context beyond the annotations: it notes that only the default branch is indexed, very common terms are ignored, and there is a ~10 searches/minute rate limit. It also discloses what is returned (matching files with repo, path, and URL). This is valuable operational detail 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 packed with useful information in a compact form. It is front-loaded with the core purpose, then provides usage guidance, supported qualifiers, return value, and limitations. Some might find it slightly long, but every sentence serves a purpose and there is no fluff.

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

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

For a tool with no output schema, the description fully explains the return value (matching files with repo, path, and URL). It also covers limitations and rate limits, making the tool predictable. Given the complexity of query construction, the description is remarkably complete for 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% for both parameters, but the description enriches understanding by showing example queries with qualifiers and explaining that qualifiers can be used directly in the query string. It adds practical usage context that the schema alone doesn't provide, though a bit more detail on per_page or query format would push it higher.

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

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

The description starts with 'Search CODE across public GitHub repositories' which is a specific verb+resource combination. It further clarifies what it can find (where a function/symbol/string is defined or used) and distinguishes it from sibling tools like search_repos and get_file_contents.

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

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

Explicit guidance is provided: 'PREFER OVER WEB SEARCH' followed by concrete use cases ('find code that does X', 'which repos use <API>', etc.). It also lists supported qualifiers, giving clear direction on query construction. This effectively tells when to use this tool over 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 cover the safety profile (readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false). The description adds no new behavioral context such as rate limits, authentication needs, or pagination behavior; it only repeats return fields which are likely in the output schema. No contradiction arises.

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 exactly two sentences, front-loaded with the main action and resource. It includes the return fields and a usage hint without unnecessary fluff. Every sentence earns its place.

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

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

Given the simple tool, complete schema coverage, presence of an output schema, and strong annotations, the description provides the essential context for an agent to select and invoke the tool. The usage hint adds extra value beyond the structured data.

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

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

Schema description coverage is 100%. The schema already provides detailed descriptions and examples for query, sort, and per_page. The description does not add any extra meaning or clarification beyond what the schema offers, so it stays at the baseline.

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

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

The description uses the specific verb 'Search' with the resource 'GitHub repositories' and specifies the search scope 'by keyword.' It clearly distinguishes from sibling tools like search_code (which searches code content) and get_repo (which fetches a single repo).

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

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

The description explicitly states when to use this tool: 'Use when exploring projects or finding code implementations.' This provides clear usage context. It does not mention when not to use it or alternatives, so it misses the full 'when/when-not/alternatives' guidance.

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

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

The description discloses implementation details beyond the annotations: BGE-base-en embeddings, cosine similarity, 500-char overlapping windows, 200K char cap with truncation flagging, and return of character offsets and similarity scores. This adds significant context while being consistent with the read-only/idempotent 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 compact paragraph but front-loads the core action, then covers use case, pairing, and technical details efficiently. Every sentence earns its place, with 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?

Given there is no output schema, the description fully covers return values (top-N passages, offsets, similarity scores), input constraints, and failure behavior (truncation flag). It also provides a clear use case and integration with a sibling tool, 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 value by contextualizing the 'text' parameter (e.g., 'SEC 10-K body', 'article') and revealing truncation behavior for inputs near the cap, which the schema does not mention. This is a slight but meaningful enhancement over 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 clearly states the tool performs semantic search inside a user-supplied record, distinguishing it from sibling tools like search_code or get_file_contents. The phrase 'Semantic search INSIDE a fetched record' is a specific verb+resource construction, and the mention of ask_pipeworx_grounded as a companion further clarifies its niche.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides a pairing with ask_pipeworx_grounded, explaining the workflow. This gives clear when-to-use guidance and names an alternative, exceeding the minimum requirement.

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=false, destructive=false, idempotent=true), the description discloses important behavioral details: OAuth requirement, inability of anonymous/BYO to persist subscriptions, SMS phone verification, the 10/day SMS cap, and the always-on feed. These add substantive context for the agent beyond what annotations provide.

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

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

The description is front-loaded with the tool's purpose and organized by subscription types and delivery channels. While dense, it contains no filler, but some examples duplicate schema descriptions, making it slightly longer than necessary.

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

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

The description covers the tool's purpose, authentication prerequisites, type-specific options, delivery channels, retrieval method, and return value (subscription ID). With a complex delivery object and no output schema, the description provides the necessary operational context for correct invocation.

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

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

The schema already provides 100% parameter coverage with detailed type-specific examples for all five subscription types. The description adds a minor semantic mapping (e.g., items:["5.02"] = officer change) but largely repeats schema content, so it only marginally raises the baseline.

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

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

The description opens with a specific verb 'Create' and identifies the resource as 'proactive monitoring subscription to a live-data event stream,' clearly distinguishing it from sibling tools like list_subscriptions and unsubscribe. It also enumerates supported types and delivery channels, fully conveying the tool's scope.

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

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

The description provides clear context for use, including the OAuth account requirement and that anonymous/BYO accounts cannot persist subscriptions. It also mentions how to retrieve alerts via recent_alerts or the registry URL. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context: it details the return content (category-bucketed example questions with tool+argument shapes) and the effect of the topic parameter, going beyond the schema.

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

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

The description is relatively long but front-loaded with example queries and a clear purpose statement. Every sentence contributes useful information, including invocation patterns and the list of categories, making the length justified without being redundant.

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 simple schema (one optional param), strong annotations, and no output schema, the description fully equips the agent: it explains what the tool does, what it returns, when to use it, what args to pass, and how it relates to sibling tools. There are no gaps in practical understanding.

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 reinforces the optional topic parameter by giving concrete examples ('finance', 'pharma', 'betting') and explaining that omitting it yields a cross-category spread. This adds practical meaning beyond the schema's bare field description.

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

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

The description clearly states a specific verb+resource+scope: it is the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from siblings by explicitly naming meta-tools and positioning this as the first tool to use when unfamiliar with 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?

The description provides 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 names alternatives (ask_pipeworx, entity_profile, compare_entities) and clarifies when to call with or without the topic argument, giving clear context.

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

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

The description goes beyond the annotations by disclosing ownership enforcement and the deactivation (not deletion) behavior. This explains why destructiveHint is false and adds meaningful context about side effects, though it does not delve into error cases or response details.

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 concise sentences, with the core action in the first sentence and each subsequent sentence adding meaningful behavioral or side-effect information. No redundancy, perfectly sized.

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 simple interface (one parameter, no output schema) and the presence of annotations, the description covers the essential aspects: the action, the ownership restriction, and the impact on historical data. It is complete and self-contained.

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

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

The schema already describes id as 'Subscription id (uuid) returned by subscribe.' The description adds a critical constraint: the id must belong to the caller's own subscription. This is additional semantic meaning relevant to the parameter, so the description 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 opens with 'Cancel a subscription by id', a specific verb+resource construction that clearly distinguishes this from subscribe and list_subscriptions. The ownership clause adds further scope, making the tool's intent 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 clear context: ownership enforcement ('you can only cancel your own subscriptions') and the consequence of deactivation (historical events stay available via recent_alerts). However, it does not explicitly mention alternatives or when-not to use the tool, so it falls short of a 5.

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

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and no destructiveness. The description adds meaningful behavioral context beyond annotations: the dual-path routing (SEC EDGAR XBRL fast path vs grounded pipeline), the exact percent-delta math tolerance behavior, the verbatim-evidence requirement, and the specific verdict categories. This gives the agent a solid mental model of what happens when invoked.

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 densely packed with diverse useful information: invocation phrases, routing logic, output summary, and performance benefit. It is front-loaded with examples and user intents. A few clauses could be tightened, but overall every sentence contributes to tool selection and correct invocation.

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

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

Despite no output schema, the description fully specifies return values (verdict categories, actual value with pipeworx:// citation, reasoning) and covers both branches of behavior. It also conveys the tool's efficiency advantage and its role in a multi-step workflow, making it complete for a 2-parameter tool.

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

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

Schema coverage is 100% with both parameters described. The description goes beyond the schema by providing concrete examples of claim strings, explaining the tolerance_pct semantics ('Set 1–2 for hallucination detection where any material error must be refuted'), and clarifying the default cap of 5%. This added context helps the agent choose appropriate values.

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

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

The description clearly identifies the tool's purpose: natural-language claim verification, with specific trigger phrases like 'fact check' and 'verify the claim that'. It specifies the resource (authoritative sources) and the two distinct paths (SEC EDGAR for company-financial claims and grounded pipeline for all others), which effectively differentiates it from related siblings like ask_pipeworx_grounded or compare_entities.

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

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

The description explicitly states when to use the tool ('Use whenever the agent needs to check whether something a user said is factually correct') and draws a clear line between company-financial claims and any other factual claim, including routing behavior. It does not name sibling tools as alternatives but the context is strong and the replacement note ('Replaces 4–6 sequential calls') provides practical guidance.

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