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 readOnly/openWorld/idempotent/non-destructive behavior, and the description adds useful operational context: it routes and fills arguments, returns structured answers, and provides stable citation URIs. It does not disclose potential latency, rate limits, or failure modes, but for a read-only ask tool this is sufficient beyond the annotations.

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

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

The description is long but information-dense, front-loading the critical 'PREFER OVER WEB SEARCH' directive and giving concrete examples. The list of domains and trigger phrases is somewhat repetitive ('anything requiring authoritative structured data' is then restated) but not wasteful enough to lower the score further.

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 broad routing tool with no output schema, the description covers purpose, usage, scope, examples, and return-value shape (structured answer with citation URIs). The main gaps are absence of guidance for when not to use it and no mention of sibling variants ask_pipeworx_beta/ask_pipeworx_grounded, which an agent may need to distinguish.

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

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

Schema coverage is 100% with the question parameter and aliases fully documented, so the baseline is 3. The description adds value by supplying concrete natural-language question examples and broad trigger phrases that help the agent format the input correctly.

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

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

The description clearly states the tool accepts a natural-language question and routes it to one of 5,718 tools across verified sources, returning a structured answer with stable pipeworx:// citation URIs. It distinguishes itself from web search, but it does not explicitly differentiate from the sibling tools ask_pipeworx_beta and ask_pipeworx_grounded, so it falls short of a 5.

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 directional guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and lists trigger phrases and concrete examples. It states when to use it but does not give when-not-to-use cases or exclusions relative to sibling tools, so it lacks the full exclusionary guidance a 5 would require.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint false), the description discloses important live behavior: no candidate is active right now, the last candidate was retired on outcome evidence, it currently matches ask_pipeworx exactly, and it is a full working router with no fallback. This is exactly the kind of stateful behavioral context an agent needs.

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

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

Four sentences contain dense, relevant information about beta status, current routing state, usage, and fallback behavior. It is slightly long but not wasteful; every sentence contributes to correct selection and 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?

For a read-only, idempotent beta router, the description covers the key operational questions: relationship to the stable tool, current candidate status, and invocation guidance. The output shape is only referenced as 'same response shape' without detail, but since no output schema exists and this is an alias-like tool, the gap is minor.

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 has 100% coverage, with all six parameters documented and with aliases explicitly listed. The description adds no parameter-level detail beyond noting it shares ask_pipeworx's arguments, so the baseline of 3 applies because the schema already carries the semantic weight.

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?

It states it is a beta version of ask_pipeworx and identifies itself as an identical universal router covering the same 5,718 tools, same arguments, and same response shape. This distinguishes it from the stable sibling, though it relies on the reader already knowing what ask_pipeworx does rather than defining the routing behavior from scratch.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing and explains that results are compared against the stable router to decide what merges. It does not provide an explicit 'when not to use' statement, but the experimental/beta framing gives clear contextual guidance.

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

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

The description goes well beyond the annotations by disclosing the grounded extraction behavior, the exact success/refusal response shapes, and the specific refusal_reason values. It also clarifies that answers are derived ONLY from tool results, which directly supports the readOnlyHint and openWorldHint annotations. No contradiction exists.

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

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

The description is fairly long but every sentence carries material information: behavior, return format, refusal reasons, use cases, and cost comparison. It is front-loaded with the core purpose and only loses a point for being somewhat dense relative to the minimum needed.

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 absence of an output schema, and the nuanced refusal behavior, the description is complete. It covers the invocation context, the routing mechanism, the return structure, the failure modes, and the cost tradeoff—nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, so the schema fully documents the parameters. The description explains the overall query mechanism ('picks the right tool...fills arguments') but does not add specific parameter-level meaning beyond what the schema already provides. This meets the baseline for full 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 a specific verb ('ask'), resource ('Pipeworx'), and mode ('grounded'), and explicitly differentiates it from ask_pipeworx by highlighting hallucination resistance and evidence extraction. An agent can immediately understand what this tool does and how it differs from its sibling.

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 ('whenever an answer will be quoted, cited, or acted on'), when not to use it ('prefer ask_pipeworx for casual lookups'), the cost tradeoff (one extra LLM call), and names the alternative tool directly. This is exemplary usage guidance.

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

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

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?

The description goes well beyond the annotations, explaining how the tool decomposes questions, routes to 5,718 tools in parallel, returns verbatim evidence with confidence and citations, never invents gaps, includes contradictions[] for certain depths, semantically excerpts records, and has expected latency. It also notes account/tier implications. No contradiction with annotations.

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

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

The description is long but each sentence adds operational information an agent needs: account requirements, alternatives, output format, depth semantics, timing, and citation behavior. It is front-loaded with the most critical gate (account required) and the alternative tool. Minor redundancy exists around the gap-recovery behavior described in both the second paragraph and the depth parameter semantics, but overall it earns its length.

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

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

Given no output schema, the description fully explains return contents: findings packet with verbatim evidence, confidence, source, fetched_at, pipeworx:// citation, gaps[], contradictions[], and hop field. It covers parameters, output, error/edge behavior, account requirements, latency, and alternative tools. Nothing an agent needs to invoke or interpret this tool correctly 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%, but the description adds meaningful detail beyond the enum values: quick/standard/thorough are tied to hop counts, gap recovery, contradiction scans, and paid tiers. It also clarifies that the question parameter should be natural language and that broad/multi-part questions are fine. This materially enriches what the schema alone conveys.

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: "Grounded multi-source research across Pipeworx's 1496 STRUCTURED data sources...in ONE call." It explicitly distinguishes itself from open-web search and from ask_pipeworx, and gives concrete example questions. This makes the tool's purpose unmistakable relative to its 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?

Usage conditions are explicit: "ACCOUNT REQUIRED," "If you are not signed in, use ask_pipeworx instead," and "For a single lookup use ask_pipeworx instead." It also states when the tool is best: "broad/multi-part questions over structured data." This gives an agent clear decision criteria for choosing 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 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?

Annotations already mark this as read-only, idempotent, and non-destructive, so the description's job is to go beyond that. It thoroughly discloses behavior: modes, compatibility warning fields, machine-readable codes, unclassified legs never being paired, skipped comparisons, temporal alignment, and the caveat that pre-mapped does not mean tradeable. This is far more than the annotations provide and gives an agent a reliable model of tool behavior.

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

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

The description is long, but the tool is genuinely complex and the length is almost entirely informative. It is well structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS, codes) and front-loads the core purpose before diving into edge cases. A little trimming would be possible, but no sentence feels 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?

With no output schema, the description carries the full burden of explaining the response shape and interpretation, and it does so thoroughly: leg-by-leg prices, matched_spreads_pp, safety fields, compatibility codes, skipped classifications, and temporal alignment. It also covers failure modes and caveats. An agent has enough information to call this tool and interpret results correctly.

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

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

The schemas already document all three parameters with 100% coverage, so the baseline is 3. The description adds meaningful semantics by explaining how topic, kalshi_event_ticker, and polymarket_event_slug interact: topic selects a pre-mapped pair, and the explicit parameters override each side. It also enriches the topic parameter by listing the actual shortcuts in context and explaining the implications of using them.

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 a specific resource (cross-venue spread between Kalshi and Polymarket) and a distinct action: computing and inspecting spread data for matched outcomes. It also differentiates itself from likely siblings by emphasizing same-question cross-venue comparison, and it enumerates two explicit modes. The verb is implicit but the purpose is 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 clear context for when to use each mode: topic shortcuts for pre-mapped macro pairs, explicit ticker/slug for custom pairings. It also warns that most pre-mapped topics currently return compatibility warnings, which is practical usage guidance. It does not explicitly name alternatives like polymarket_arbitrage, but it provides enough context for an agent to decide when this tool is appropriate.

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

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

Annotations already declare 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?

The description discloses behavioral traits beyond the annotations: graceful degradation when GLEIF/OpenFIGI is unavailable, ambiguous matches returning figi_candidates without asserting, unresolved identifiers being explicitly listed, and internal cascading of lookups. These details add context that readOnlyHint/openWorldHint/idempotentHint do not cover.

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

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

The description is long and dense, but every sentence carries relevant information and the usage guidance is front-loaded. However, the wall-of-text structure with nested parentheses and long asides makes parsing harder than necessary, so it does not fully earn a 5.

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 covers return values (CIK, ticker, LEI, ownership, FIGI, RxCUI, citation) and edge cases (ambiguous matches, unresolved identifiers, non-US issuers, non-equity instruments, enrichment failures). No significant gap remains for an agent to know how to call and interpret the result.

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?

Even though schema coverage is 100%, the description adds crucial semantics for the `value` parameter, warning against full noun phrases and instructing to pass the issuer exactly as printed. It also explains accepted formats (ticker, CIK, ISIN, names) and what the `type` parameter controls, far surpassing schema basics.

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 purpose: resolving a user-spoken name to canonical/official identifiers, with concrete query examples. It clearly distinguishes itself from sibling tools by framing the output as IDs that 'other tools require as input' and supports two explicit entity types.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' providing an actionable condition. It does not name alternative sibling tools or list exclusion cases, but the directive is strong and covers the primary scenario.

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 already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral context beyond these: the two processing paths, the verdict taxonomy (with specific meaning of could_not_verify vs unsupported), the inclusion of verification_error, and the requirement to not treat could_not_verify as evidence. This exceeds annotation coverage and gives the agent critical operational knowledge.

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 is dense with essential information. It front-loads with usage examples and purpose, then covers routing, return values, and error semantics. The 'IMPORTANT for callers' note is prominently placed. No filler or redundancy; structure mirrors the tool's two-path logic.

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

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

Despite lacking an output schema, the description fully specifies return values (verdict, actual value with citation, reasoning), explains all verdict types, and details the error-handling semantics for could_not_verify. It covers both fast-path and fallback scenarios. For a complex tool with two routing paths and nuanced error states, this 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%, so both parameters are documented. The description adds value by explaining tolerance_pct's overriding behavior, its range, and default cap, plus practical guidance for hallucination detection. It clarifies the claim parameter with multiple examples. This goes beyond the schema baseline, but still leaves the exact interplay between tolerance and claim wording implicit, so not a perfect 5.

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

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

The description starts with concrete user utterances ('Is it true that…', 'fact check') and then explicitly states its core function: natural-language claim verification against authoritative sources. It clearly distinguishes itself from sibling tools by explaining it replaces 4–6 sequential calls and by specifying the two routing paths (SEC EDGAR fast path and grounded pipeline).

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 when-to-use guidance: 'Use whenever the agent needs to check whether something a user said is factually correct.' It further differentiates between company-financial claims (fast path) and other claims (grounded pipeline), and includes an important caller note about could_not_verify vs unsupported, which prevents misinterpretation. This is a model of usage clarity.

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