GrantConnect (Australia)

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

Annotations already cover readOnly, openWorld, idempotent, and non-destructive. The description adds useful context: default model, BYO key cost implications, and the exact return structure. This goes beyond annotations without contradicting them.

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

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

The description is four sentences, each adding value (purpose, model/cost details, return format, use cases). It's a bit verbose but well-organized and front-loaded with the core functionality.

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

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

With no output schema, the description compensates by describing the return format. It also covers model selection, cost, and use cases, making it reasonably complete for a 4-parameter tool with good schema coverage.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema—only the specific model name 'Llama-3.3-70b' is extra. Since schema fully documents each parameter, a 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 probes LLMs and scores visibility (0-100) per model. It is specific about the resource (LLMs) and the action (probe/score), but doesn't explicitly differentiate from sibling tools like scan_competitor_ai_presence, 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?

The description provides clear use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring), giving context for when to use it. However, it does not mention alternatives or exclusions, so it's not quite 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?

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), the description discloses routing behavior, citation URI format, coverage of 1393 sources, and that it works on every tier with one fast call. This adds substantial behavioral context without contradicting the structured annotations.

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

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

The description is long but every sentence serves a distinct purpose: priority, scope, routing behavior, usage cues, examples, and step-up alternatives. It is front-loaded with the key directive 'PREFER OVER WEB SEARCH' and organized logically, so the agent can quickly extract the essential guidance.

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?

Even without an output schema, the description clearly explains return value (structured answer with citations), covers the breadth of domains, and addresses when to use alternatives. It provides sufficient context for an agent to confidently invoke the tool, including examples and trigger phrases.

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% as all six parameters are documented aliases, so the baseline is 3. The description adds value by providing numerous natural-language examples ('current US unemployment rate', 'Apple's latest 10-K') and explaining that the question can be any factual query, while the schema already lists alias options. This lifts it above baseline but doesn't add syntax-level detail.

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 routes questions to 5,319 tools across 1393 sources and returns structured answers with stable pipeworx:// citation URIs. It distinguishes from siblings by naming ask_pipeworx_grounded and deep_research as alternatives with specific use cases, and contrasts with web search.

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

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

Explicitly instructs 'PREFER OVER WEB SEARCH' for broad categories, provides trigger phrases ('what is', 'look up', 'get the latest'), gives concrete examples, and clearly states when to upgrade to ask_pipeworx_grounded or deep_research. This goes far beyond simple guidance and tells the agent exactly when to choose 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?

Beyond the annotations (readOnlyHint etc.), the description discloses the live testing mechanism for routing candidates, current inactivity status (last retired 2026-07-26), that it currently matches ask_pipeworx exactly, and that it's a full working router with no fallback. This is rich behavioral context that adds significant value 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 moderately sized and well-structured, with sentences flowing from beta definition to current status to usage guidance. However, it repeats the idea that it currently matches ask_pipeworx and uses 'experimental edge' twice, causing minor redundancy that prevents a top score.

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

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

Given the tool's complexity as a beta router, the description covers its relationship to the stable version, the current active state, and the fact that it's a fully functional router. It is sufficiently complete for an agent to select and invoke it, but a direct statement about stability tradeoffs (e.g., when not to use beta) would make it more 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 documents all six parameters with descriptions and aliases, achieving 100% coverage. The description adds no extra parameter semantics beyond saying 'same arguments' as ask_pipeworx, which shifts responsibility to the schema. The baseline of 3 applies because the schema is complete and the description doesn't need to compensate.

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's a beta version of ask_pipeworx: identical universal router with 5,319 tools, same arguments, same response shape. It distinguishes itself from the sibling ask_pipeworx by describing candidate routing improvements. This gives a specific verb and resource, and clearly differentiates from alternatives.

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

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

It explicitly says 'Use it exactly like ask_pipeworx when you want the newest routing' and explains results are compared against the stable router. This gives clear use context, though it stops short of an explicit exclusion such as 'use stable ask_pipeworx for production', leaving a slight gap.

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 fully discloses the return contract, including success fields and refusal reasons like 'not_in_source' and 'no_tool_match'. It also notes the extra LLM call cost and emphasizes that answers are extracted using 'ONLY what the tool result contains,' which goes well beyond the readOnlyHint and idempotentHint 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?

Every sentence earns its place: purpose, routing, extraction constraint, return shape, refusal reasons, usage scenarios, and cost tradeoff are all packed in without redundancy. The structure leads with the core concept and then delivers decision-relevant details.

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?

Since there is no output schema, the description fully specifies success and failure return structures, including concrete refusal reason strings. It also explains the internal tool routing (5,319 tools across 1,393 sources), which is sufficient for an agent to understand the tool's scope and limitations.

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

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

Schema coverage is 100% — all six parameters are documented aliases for 'question,' and the schema already states each accepts natural language. The description does not add parameter-specific semantics beyond the internal routing explanation, so the baseline 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' making the core purpose explicit. It distinguishes from sibling ask_pipeworx by stating 'Same routing as ask_pipeworx' but adding the grounded extraction and explicit refusal 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?

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts (financial verdicts, legal claims, medical lookups, public statements).' It also names the alternative and gives an exclusion: 'prefer ask_pipeworx for casual lookups.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, and the description does not contradict these. It adds meaningful behavioral detail: the record includes recipient org, ABN, address, funding agency, dates, selection process, flags, and the conditional fetching/inlining of a linked grant opportunity when go_id exists. This goes beyond the annotation safety profile, though it does not discuss error handling or rate limits.

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

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

The description is a single dense sentence that efficiently enumerates the record contents and the conditional inlining behavior. It is front-loaded with the core purpose and then details the return fields. While lengthy, every clause adds value and there is no fluff. It could be split for readability, but it remains 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?

With no output schema, the description must carry the full burden of explaining return values. It does so comprehensively: recipient organisation with ABN/address, funding agency, PBS program, grant program/activity, purpose, AUD value, dates, selection process, location, flags, and the linked grant opportunity when available. This makes the tool's behavior fully predictable for an agent, even without an output schema.

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

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

Schema coverage is 100% — the schema already documents ga_id with an example and the 'bare number accepted' rule. The description restates the parameter name and example but adds no new semantic information beyond what the schema provides. Therefore, 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 'Full record for one awarded Australian Commonwealth grant, looked up by its GrantConnect award id', providing a specific verb (looked up) and resource (awarded grant record). It clearly distinguishes itself from sibling search tools (au_grants_search, au_grants_by_recipient) by focusing on ID-based lookup and enumerating the exact fields returned, leaving no ambiguity about what the tool does.

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

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

The description clearly implies the use case: when you have a specific grant award ID (ga_id) and need the complete record. It explains that the tool fetches a single record by ID, and the conditional inlining of the linked opportunity when go_id is present adds context. However, it does not explicitly state when not to use it or name alternative tools for searching, 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 indicate read-only, open-world, and idempotent behavior. The description adds transparent details: results are sorted by soonest closing, days remaining are computed at request time, and it enumerates the exact data fields returned. This goes beyond the structured annotations.

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

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

Three sentences: first states the core purpose and source, second lists the returned fields, third explains filters and the user question. Perfectly front-loaded with no redundant content.

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

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

For a read-only list tool with no output schema, this description is comprehensive: it lists all fields returned, defines the ordering and dynamic date computation, includes filtering options, and provides a motivating question. It equips an agent to invoke the tool correctly without needing additional context.

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

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

Schema descriptions cover all 6 parameters at 100% coverage. The description echoes filter options (category, agency, title) but does not add new semantics or syntax details beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists Australian Commonwealth grant opportunities still open for application, specifically GrantConnect opportunities with future close dates. It uses specific verbs and resource names, and distinguishes itself from siblings by focusing on 'open' opportunities and directly answering the question 'what Australian federal grants can I still apply for'.

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: it is for open grants sorted by soonest-closing, with specific filters. It does not explicitly mention when not to use or name alternative tools, but the purpose is unambiguous enough for an agent to select this tool appropriately.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, etc. The description adds meaningful behavioral context: matching logic (substring vs exact ABN), accepted ABN formats, and the return structure including totals and per-agency breakdown. It contradicts nothing.

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

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

The description is three sentences, front-loaded with the core function, then return values, then the question it answers. No redundant information.

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

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

Despite having no output schema, the description clearly enumerates the return fields (total AUD, number of awards, first/last dates, per-agency breakdown) and explains the matching modes. It doesn't explain pagination behavior, but the schema covers limit/offset. This is sufficient for an agent to select and invoke correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description restates ABN formats and matching modes already present in the schema but does not add new parameter-level meaning beyond the schema. It does help frame the overall purpose, but for individual parameter semantics it doesn't add much.

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 and resource: 'Every Australian Commonwealth grant awarded to one organisation' and clearly distinguishes from siblings by focusing on recipient matching and aggregation. It names the matching methods (name substring or exact ABN) and the output (funding total, per-agency breakdown), making it distinct from au_grants_search or au_grant_award.

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 the use case by stating it answers 'how much Commonwealth grant money has this charity... received, and from whom.' This gives clear context for when to use the tool. However, it does not explicitly name alternatives or exclusions, so it's not 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?

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description adds valuable behavioral detail: it explains that free-text queries are case-insensitive substrings matched across specific fields, that multiple words are AND-ed, and that results are sorted newest-first by default. It also enumerates the returned data fields. No contradictions with annotations.

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

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

The description is a single paragraph of about five sentences, each packing useful information: source, output fields, matching semantics, filters, sorting, and a summary question. It is not excessively long, though it does repeat some details already present in the schema (e.g., query substring matching). Overall, it is well-structured and front-loaded with the main 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 tool with 13 parameters and no output schema, the description is remarkably complete. It specifies the data source (GrantConnect), the exact output fields, the matching behavior, and all filter categories. It also gives a high-level use-case summary ('who received... how much, and when'). This makes the tool self-explanatory without needing to inspect the schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by providing concrete examples for filters (e.g., agency 'Department of Social Services', category 'Social Inclusion'), listing valid recipient_state values, and clarifying that awarded_from/awarded_to refer to the publish date. These examples go beyond the schema property descriptions, which often only say 'substring match'.

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: 'Search awarded Australian Commonwealth government grants from GrantConnect'. It clearly enumerates the output fields and ends with the exact question it answers ('who received Australian federal grant money for X, how much, and when'). This differentiates it from siblings like au_grants_by_recipient and au_grants_top_recipients, which are more specialized.

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: when needing to search awarded grants with flexible filters (agency, category, state, value, date). However, it does not explicitly mention alternatives or exclusion conditions, such as pointing to au_grants_by_recipient for recipient-specific queries or au_grants_opportunities_open for open opportunities.

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 that the response includes the number of award rows scanned and whether all matching rows were covered, providing transparency about partial results. This complements the readOnlyHint and idempotentHint 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?

Three sentences, front-loaded with the main action, and every sentence adds value: the ranking purpose, filtering and scan behavior, and the answering of a common question. 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?

The description covers the core purpose, filters, output characteristics (award counts, agencies, coverage indicator), and an example question it answers. It lacks explicit return format details, but the absence of an output schema is partially mitigated by the description's mention of scanned rows and counts.

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 each parameter has a description. The tool description reinforces the date-range and scan_limit concepts but does not add significant extra meaning beyond the schema, justifying the baseline score.

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

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

The description clearly states the tool ranks organisations by total Australian Commonwealth grant money received, with award counts and funding agencies. This specific verb+resource+scope distinguishes it from siblings like au_grants_by_recipient, which focuses on per-recipient grants rather than top recipients.

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

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

The description specifies filtering by agency, category, state, and date range, and explains the scan_limit nuance that helps users understand when a ranking is partial. It does not explicitly compare against alternatives, but the context is clear enough for selection.

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?

This description goes well beyond the annotations (readOnlyHint, openWorldHint, etc.) by detailing critical behaviors: low-confidence matches short-circuit with status, closed/dead markets return a specific status and skip fan-out, wide-spread markets flag tradeability, and resolution-rule risk is disclosed with examples like refund_50_50. The description also warns about blocking routes and the need to inspect resolver fields before trusting analysis, which is highly transparent.

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

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

The description is long but well-structured, using capitalized section headers and bullet-like examples to navigate dense information. The opening sentence front-loads the core purpose, and while every section contributes value, the sheer length and level of detail could be overwhelming; however, it is justified 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?

Despite having no output schema, the description provides thorough coverage of the response shape: it details the result.market, result.analysis, result.evidence, parent_event extractor, news fields, resolver contract, safety mechanisms, and resolution-rule risk. It also explains edge cases like low-confidence matching and closed-market handling, making it fully complete for an agent to invoke and interpret 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 covers all three parameters with 100% coverage, including defaults and descriptions. The tool description enhances this by providing concrete slug/URL/question examples, explaining the fan-out depth difference between 'quick' and 'thorough' via examples, and clarifying the size implications of include_raw. It adds practical context not present in the schema, though the schema already does a solid job.

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

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

The description opens with a clear, specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It distinguishes itself from siblings by detailing the classification system, fan-out behavior, and the market-vs-model comparison output, making its unique role obvious.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides extensive contextual guidance, including what happens with low-confidence matches, closed markets, and wide spreads, effectively telling the agent when the tool will be useful and how to interpret different result states.

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 the tool as read-only and idempotent, which the description does not contradict. The description adds substantial behavioral context: data sourcing from SEC EDGAR/XBRL, off-calendar fiscal year handling, sorting by primary metric, and the return format with paired data and citation URIs. This goes well beyond 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 dense and front-loaded with trigger phrases and purpose. Every sentence contributes usage or behavioral detail, though the length is slightly beyond the minimum needed. It is well-structured and each clause earns its place, but a touch more brevity could improve scannability.

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 still explains the return shape (paired data + pipeworx:// citation URIs), the types of data sources, sorting behavior, and the entity count limit. Combined with the sibling tools, it gives the agent enough context to decide when to use this tool and what to expect.

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

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

Schema coverage is 100% with clear descriptions for both parameters. The description further enriches semantics by specifying what metrics are pulled for each entity type, giving example tickers/names, and reinforcing the 2–5 entity limit. This adds value beyond the schema without duplicating it.

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 explicit trigger phrases and states the core function: 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly distinguishes itself from sequential single-pack lookups and makes the tool's scope and resource explicit.

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

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

It explicitly says 'ALWAYS PREFER over sequential single-pack lookups when comparing entities,' providing a clear when-to-use directive and naming the alternative approach. It also differentiates between company and drug types, telling the user which data sources are relevant per type.

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

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

The description goes far beyond the annotations, disclosing account requirements, parallel decomposition, return packet contents (evidence, confidence, source, fetched_at, citation, gaps[], contradictions[]), the 'never invented' guarantee, semantic excerpting behavior, and timing expectations (15-90s). It also explains how depth levels alter execution. No contradiction with annotations exists — actually, the openWorldHint is refined by clarifying this is not open-web search.

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

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

The description is long but every sentence carries unique operational value (auth tier, source scope, examples, exclusions, output details, timing). It is front-loaded with the most critical caveat (account requirement) and maintains a logical flow: what → when → how → output → performance. 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?

There is no output schema, so the description bears the full burden of explaining return values — and it does so thoroughly: findings packet, gaps[], contradictions[], hop field, citation_uri, semantic excerpting. Combined with explicit timing, limitations, and usage alternatives, this is a complete operational picture for such a complex 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, but the description adds substantial semantics beyond the schema. It explains what constitutes a good `question` (broad/multi-part is fine, decomposition is the point) and elaborates on each `depth` value's behavioral implications (gap recovery, contradiction scan, lead chasing). This goes well beyond the schema's enum 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 performs grounded multi-source research across Pipeworx's structured data sources in a single call, distinguishing it from open-web search. It includes concrete examples of suitable questions and explicitly contrasts it with ask_pipeworx, so purpose and differentiation are both strong.

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?

This is exemplary. It states when to use deep_research (broad/multi-part questions over structured data), when NOT to use it (single lookups use ask_pipeworx; breaking/current-news topics prefer ask_pipeworx), and even provides a fallback for unsigned-in users. Explicit alternatives and exclusions are all present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it returns top-N results with full input schemas and curated examples, and notes that results are 'ready to call directly, no second schema lookup needed.' This goes beyond the annotations by explaining the output format and usage flow, though it doesn't disclose any potential rate limits or pagination behavior.

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

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

The description is front-loaded with the core purpose and is concise overall. The list of domains is long but useful as examples of what to search for, and every sentence adds value (purpose, when to use, return behavior, and first-step advice). It is not overly verbose, though the domain list could potentially be trimmed without losing meaning.

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

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

For a discovery tool with no output schema, the description compensates by explaining what is returned: 'names, descriptions, and full input schemas (with curated examples)' and notes that results are ready to call directly. Given the tool's complexity is moderate (single required parameter, many aliases) and annotations cover safety, the description provides adequate context for an agent to understand the tool's role, invocation, and output. It doesn't specify the exact JSON response structure, but the stated return contents are 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 description coverage is 100%, with all parameters (query, aliases, limit) fully described in the input schema. The description does not need to add much, but it reinforces that the query is a 'natural language description of what you want to do' and mentions 'top-N' which aligns with the limit parameter. No additional syntax or format details are missing, so a baseline 3 is appropriate.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Find tools by describing the data or task.' It explicitly distinguishes itself from sibling domain-specific tools by listing the covered domains and positioning itself as a meta-level discovery tool, saying 'Call this FIRST when you have many tools available.'

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).' This clarifies its role as the entry point compared to the many sibling tools, and implicitly advises against using it when you already know the specific tool.

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

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

Annotations already cover readOnly/idempotent/destructive safety, and the description adds substantial behavioral context: 'soft-fails until reactivated' for patents, 'GDELT→GNews fallback', specific return fields, and parameter constraints. 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 densely informative—every sentence serves a purpose (examples, purpose, usage, sources, return details, parameter note). It is front-loaded with trigger phrases and follows a logical structure, though it could be slightly tighter.

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 thoroughly covers return fields, data sources, fallback behavior, limitations (patent sunset, names not supported), and usage context. It gives an agent everything needed to select and invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description provides examples ('AAPL', '0000320193') and restates the zero-padded CIK requirement, but adds no new semantic meaning beyond what the schema already documents.

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 'full cross-source profile of a US public company' and uses specific verbs like 'research', 'brief me', and 'profile'. It distinguishes itself from sibling tools by emphasizing 'ONE parallel call' vs chaining single-pack lookups, and provides concrete user-intent examples.

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 direct guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view' and 'names not supported (use resolve_entity first if you only have a name)'. This clearly states when to use and when to use alternatives.

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

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

The description adds context beyond annotations by clarifying it deletes a previously stored memory and mentioning sensitive data clearance. Annotations already indicate destructive and idempotent behavior, and the description does not contradict 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, and every sentence adds value (what, when, relationship to siblings). No unnecessary words 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?

Given the tool's simplicity (one param, no output schema) and rich annotations, the description covers the essential context: what it does, when to use, and how it fits with siblings. It is complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the parameter's meaning ('Memory key to delete') is fully captured. The description only says 'by key', adding no new semantic details, hence a baseline score of 3.

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

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

The description clearly states 'Delete a previously stored memory by key', using a specific verb and resource. It distinguishes itself from sibling tools remember and recall by explicitly pairing with them, 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 when-to-use guidance: 'stale context, task done, or you want to clear sensitive data'. It does not explicitly list when-not-to-use or alternative tools, but the guidance is clear and actionable, warranting a strong score.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable context by explaining that it fetches the page, extracts specific content, and returns a text blob in standard llms.txt format, which clarifies the network side effect and output shape. It doesn't mention fetch errors or rate limits, but the annotation coverage lowers that burden.

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

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

Three sentences deliver the action, process, and use cases with no fluff. The first sentence front-loads the core purpose ('Generate a production-ready llms.txt file'), and every clause 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?

For a simple two-parameter fetch-and-format tool, the description covers input, processing, output format, and intended deployments. It even implies the return value ('single text blob ready to drop at site-root/llms.txt'), which compensates well for the absence of an output schema.

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

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

The schema already describes both parameters with 100% coverage, including default and max for max_links. The description's mention of 'key links' aligns with max_links but adds no new parameter-level meaning beyond the schema, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Generate a production-ready llms.txt file for any URL') and clearly states what the tool does: fetches a page, extracts title/description/key links, and emits standard llms.txt markdown. This distinguishes it from sibling tools like ai_visibility_check or scan_competitor_ai_presence, which focus on checking/scanning rather than generating.

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?

Three concrete use cases are listed — indexing a client's site, drafting for a project, and auditing a competitor — providing clear context on when to use the tool. However, it does not explicitly name alternative tools or state when not to use it, so it falls just 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 the tool as read-only, idempotent, non-destructive, and open-world. The description goes further by detailing exactly what coverage information is exposed: ingest windows with status and row counts, date ranges, total rows, and error windows. This adds meaningful behavioral context beyond the annotation flags, with no contradiction.

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

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

The description is two sentences with a clear 'what' and 'when to use' structure. The first sentence enumerates specific items without redundancy, and the second provides actionable guidance. Every phrase adds value, making it highly concise and well-structured.

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

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

The description fully specifies the return contents: ingest windows with status/row counts, date ranges, total rows, and errors. It also provides the necessary context for when to trust the data. With no parameters and strong annotations, this is a complete description for the tool's purpose.

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 is an empty object with no parameters. Because there are no parameters to document, the description rightly omits parameter semantics. The baseline for zero-parameter tools is 4, and the description needs no further addition.

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 reports current GrantConnect data coverage, including ingest windows, row counts, date ranges, and errors. It distinguishes itself from search/query tools with the explicit 'Use this before trusting a date-bounded answer about Australian grants.' This provides a specific verb (shows/holds) and resource.

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 direct usage guidance: check this tool before trusting date-bounded answers about Australian grants. It frames the coverage check as a prerequisite for reliable queries. It doesn't name specific alternatives, but the context 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds that subscriptions are scoped to the caller and lists the returned fields, which is useful context beyond annotations. No contradiction.

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

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

The description is two sentences, front-loaded with the action and scope, then returns fields, then usage guidance. Every sentence earns its place with zero waste.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description fully covers the purpose, return fields, and usage context. It explains the default 'active' scope and how to use it with subscribe/unsubscribe, making it 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?

Input schema has 100% coverage for the single parameter include_inactive, with its own clear description. The tool description does not add additional parameter semantics, but the schema already provides sufficient meaning, so baseline 3 is appropriate.

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

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

The description clearly states the function: 'List the caller's active subscriptions.' It specifies the resource (subscriptions), the scope (caller's active), and lists the return fields (id, type, params, created_at, etc.), distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

The description explicitly provides usage guidance: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This tells the agent when to use the tool relative to subscribing and unsubscribing, with 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 annotations are all false and offer little guidance, so the description carries the burden. It discloses rate limiting ('Rate-limited to 5 per identifier per day'), quota exemption ('doesn't count against your tool-call quota'), and the impact on roadmap ('signal directly affects roadmap'). This adds useful behavioral context beyond the annotations, though it doesn't describe the asynchronous nature of feedback or whether a confirmation is returned.

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

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

The description is compact and front-loaded with the core purpose, followed by usage scenarios, formatting guidance, and operational quirk (rate limit, quota). Every sentence earns its place; no filler or repetition of schema content.

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

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

For a simple feedback tool with full schema coverage, the description covers the essential context: when to use, how to frame feedback, what to avoid, and the rate-limit/quota behavior. The absence of an output schema is acceptable since the tool likely returns an acknowledgment, and the description doesn't need to explain return values.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by guiding message content ('Describe the issue in terms of Pipeworx tools/packs') and specifies what not to include ('don't paste the end-user's prompt'), which goes beyond the schema's plain-text description. It also implicitly reinforces the type parameter's semantics by naming bug, feature/data_gap, and praise.

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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It enumerates concrete feedback types (bug, feature/data_gap, praise) and naturally distinguishes itself from sibling tools like ask_pipeworx by framing it as reporting issues rather than asking questions.

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: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also gives clear exclusions/instructions: don't paste the end-user's prompt, describe in terms of Pipeworx tools/packs.

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 valuable behavioral context beyond the annotations: it discloses data provenance (CF analytics-engine), privacy (no PII), and caching behavior (5min-1h depending on window). This enriches the reader's understanding without contradicting the readOnly and idempotent 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 (three sentences) and front-loaded with the core purpose. The second sentence is structured as a list of use cases, making it easy to scan. Each sentence contributes meaningful information, with no filler.

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

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

Despite having no output schema, the description comprehensively covers the tool's inputs (window), output (top tools, packs, call volume), data source, privacy, caching, and practical use cases. It addresses all relevant aspects for a low-complexity tool with a single optional parameter.

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 a complete description for the 'window' parameter, including the default and the trade-off between shorter and longer windows. The tool description merely restates the window options without adding further semantic value, so it meets the baseline of 3.

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

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

The description clearly states the tool's function with a specific verb ('Returns') and resource ('top tools, top packs, and total call volume'). It distinguishes itself from siblings by emphasizing it shows what other AI agents are calling on Pipeworx, derived from CF analytics-engine.

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 lists three explicit use cases, giving clear context on when to use the tool. However, it does not mention exclusions or name alternative sibling tools, so it falls short of a perfect score.

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

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

Beyond the annotations (readOnly, idempotent, not destructive), the description discloses the underlying algorithms (monotonicity, partition-sum), the `>3pp` threshold, the `0.30` Jaccard similarity anchor, placeholder filtering, and an important fill-check caveat advising against trading when realizable edge ≤ 0. This gives the agent practical knowledge about the tool's behavior and limitations, which 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 long but densely packed; it introduces capitalized concept labels (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) that aid scanning. However, some redundancy exists between the partition_check explanation and the response field list, and the length may make the entry point harder to parse quickly.

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 and two parameters, the description fully specifies the response structure (opportunities[] and partition_check fields), explains the fill-check pricing details, and covers behavioral edge cases (similarity threshold, placeholder fraction, live book). It also points to sibling `polymarket_fill_risk` for custom sizing, completing the contextual picture.

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

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

The input schema already documents both parameters (event and topic) with examples, and the description adds richer semantic meaning by explaining how each parameter is used internally (e.g., `event` walks child markets and computes partition checks; `topic` flattens related events). The description also clarifies the argument forms (slug vs URL, seed question), exceeding schema-level detail.

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 pairing ('Find arbitrage opportunities on Polymarket') and explains the two distinct operation modes (`event` and `topic`), distinguishing it clearly from sibling tools like `polymarket_edges` or `polymarket_fill_risk`. It also clarifies the no-args default behavior, making the tool's 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 explicitly states when to use each mode: no args for a broad trending scan, `event` for a specific market, and `topic` for cross-event scanning. It even names an alternative tool for custom sizing (`polymarket_fill_risk`), providing clear context for selecting between 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 far beyond the annotations by disclosing internal response structure (by_segment, fed_candidates, _diagnostics), caching ('Cached 1h at the KV level keyed on all knobs'), edge computed net of slippage, the 24h-move warning, and why fed candidates are excluded. It also explains why segments might be empty via filter_skips, making behavior predictable. No contradiction with annotations.

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

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

The description is dense but front-loaded with a clear purpose. Every paragraph serves a structural role (segments, knobs, response top-level). However, some details like 'gates relaxed Run 8 from prior 85%/5%/50:1' and exhaustive placeholder-slug examples are arguably beyond the core need and add length without proportional value. Overall, it is well-organized but not perfectly lean.

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 thoroughly covers the return structure: by_segment with all three segment definitions, per-opportunity fields (edge_pp_net, kelly_fraction, market.liquidity, etc.), and diagnostics. It also explains parameter effects and caching. For a tool of this complexity, the description is remarkably complete, leaving no major behavioral or output ambiguity.

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

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

Schema description coverage is 100%, so the baseline is 3. The description mentions the tradeable-edge knobs (min_liquidity, max_spread_pp, min_partition_leg_kelly) and how they affect opportunities, but the input schema already provides full descriptions for each parameter. The description adds no new syntax, format, or interaction details beyond the schema, so it does not deserve 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 opens with a specific verb+object pair: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly states the tool's purpose, scope, and the unique value proposition. It also distinguishes itself from siblings by naming three distinct output segments (model_driven, structural_arbitrage, concentrated_longshot) and the intent 'what should I bet on today'.

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: 'built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains when to use (opportunity discovery) and even mentions alternative approaches implicitly (not paging hundreds of markets). However, it does not explicitly name sibling tools or state when NOT to use this tool, so it stops 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, idempotentHint, and destructiveHint=false. The description adds valuable behavioral details beyond these: the 60-day TTL limit, decay computed from daily closes rather than intraday, and the meaning of snapshot gaps (cache-miss days). These are non-obvious traits that significantly inform usage.

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

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

The description is dense but well-organized: it opens with the core purpose, then uses labeled sections (Args, RESPONSE, LIMITS) to structure additional detail. Every sentence provides operational value, but it is somewhat lengthy. Still, it avoids redundancy and front-loads the most critical information.

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

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

With no output schema, the description fully explains the return structure (tracked[], expired[], snapshot_dates[]) including field semantics and even interpretive guidance (e.g., 'median lifespan is your competition clock'). It also covers data availability limits (TTL, snapshot start, gaps). This is a complete, self-contained explanation for a moderately complex 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%, with both parameters (days, window) already documented with defaults and ranges. The description's recap ('days (lookback, default 14, max 30)') adds nothing beyond the schema, and even slightly under-specifies by omitting the 'clamp 2-30' minimum. Since the schema does the heavy lifting, 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 function as 'edge persistence and decay telemetry' and answers a specific question: 'how long has this edge existed and is it shrinking?' It distinguishes itself from siblings like polymarket_edges by emphasizing the temporal/persistence aspect, making it clear this is a specialized analysis tool rather than a general edge listing.

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 strong contextual guidance by illustrating a use case ('a fresh wide edge and a 3-week-old wide edge are different trades') and explaining when this tool is valuable. It doesn't explicitly name an alternative tool, but the contrast with polymarket_edges is implied through the 'built from daily snapshots' framing, giving the agent enough context for selection.

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

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

Despite annotations already marking this as read-only and non-destructive, the description adds substantial behavioral detail: it walks the order-book ladder, returns specific fields (top_of_book, vwap_fill_price, slippage_pp, thin_legs, forced_directional_risk), and clarifies interpretation of inputs like size_usd. It even explains the risk of partial basket fills converting an arb into a directional position, which is crucial behavioral context beyond the annotations.

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

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

The description is long but every sentence earns its place. It is front-loaded with a crisp purpose sentence, then structured into SINGLE-MARKET and BASKET sections with clear output lists and usage warnings. The density is justified by the tool's complexity and the need to communicate both modes and edge cases.

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 modes, four parameters, no output schema), the description is remarkably complete. It covers inputs, defaults, outputs, risk factors, and usage context, and also compensates for the lack of required parameters in the schema by clearly stating the market-or-event requirement. There is no significant gap in the information an agent would need to invoke it correctly.

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

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

Schema coverage is 100%, but the description adds considerable semantic value beyond the schema. It clarifies the one-of requirement (market or event), the dual interpretation of size_usd (max spend vs settlement notional), and default behaviors (side auto-detection in basket mode). This goes well beyond the property descriptions in the schema.

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

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

The description states a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes two modes (single-market vs basket) and explicitly positions itself relative to sibling tools like polymarket_arbitrage and polymarket_edges, 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 when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable) and warns about partial fills, giving strong context 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?

With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint=false, the description adds substantial behavioral context: compatibility_warning firing conditions, temporal_alignment meaning, skipped_cross_type/subtype semantics, and the explicit statement that aligned:false means spreads are 'mathematically meaningless.' It goes far beyond the annotations and prepares the agent for unexpected empty or warning-laden results.

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

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

The description is long but every section earns its place: purpose, two modes, response format, safety fields, and a meta-caution. It is front-loaded with the core definition, uses capitalized labels for scannability, and contains no fluff or repetition of schema descriptions. 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?

Although there is no output schema, the description thoroughly explains the response structure: 'each venue's leg-by-leg prices (raw probability 0-1) plus matched spread[].top_spreads_pp,' and interprets the safety fields (compatibility_warning, temporal_alignment, skipped_cross_type/subtype). It also covers edge cases like non-equivalent bet shapes and semantically unrelated events, making the tool self-contained for an AI agent.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by describing modes: 'topic' auto-fetches matching events on each venue, while kalshi_event_ticker and polymarket_event_slug 'Override the topic-mapped' side. It also enumerates the topic shortcuts in the schema, but the description explains how they function in the two-mode workflow, which adds real value.

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

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

The description opens with a specific verb and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It clearly distinguishes from siblings like polymarket_arbitrage by focusing on the cross-venue Kalshi-Polymarket dimension and stating that the delta is a real signal only when bet shapes are equivalent.

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 explains two invocation modes (topic shortcuts vs explicit overrides), how overrides interact, and provides strong cautions: 'Real cross-venue spreads are rarer than the macro-shortcut list suggests' and 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly name alternative sibling tools, but the context sufficiently tells the agent when and how to use this tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description focuses on additional traits: scoping to the agent's identifier (anonymous IP, BYO key hash, or account ID) and the dual retrieve/list behavior based on the key argument. This enriches beyond the structural 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?

Three sentences front-load the core action, immediately cover use cases, and then explain scoping and sibling relationships. Every clause carries weight 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?

The tool is simple (1 optional parameter, no output schema) and the annotations already cover side-effect safety. The description provides all necessary context: what it does, when to use it, scoping rules, and how it fits with remember/forget—leaving no critical gaps for an agent selecting or invoking 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?

The schema fully documents the single 'key' parameter at 100% coverage, but the description goes further by providing example key contexts (user's target ticker, address, research notes) and reinforcing the omission-for-list semantics. This adds practical meaning beyond the schema's minimal 'omit to list all keys'.

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

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

The description opens with a specific verb-resource pair ('Retrieve a value previously saved via remember') and immediately contrasts with listing all saved keys. It names sibling tools (remember, forget) and clearly differentiates recall as the retrieval operation.

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

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

It explicitly states when to use the tool ('Use to look up context the agent stored earlier') and gives concrete examples (target ticker, address, research notes). It also instructs to pair with remember and forget, providing clear workflow guidance and implicit exclusions (don't re-derive what's already stored).

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 and idempotentHint=true, but the description explicitly states that mark_read:true flags returned events as read so future calls return only newer events. This is a persistent state change, contradicting readOnlyHint (and idempotency when mark_read=true). This is an annotation contradiction.

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

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

Three sentences that front-load the core purpose, then add filtering, mark_read behavior, and polling/alternative access in an efficient, well-ordered way. No filler words.

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

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

For a 5-param read tool with no output schema, the description covers returned event structure, filtering, and read-state behavior. It omits limit and unread_only details, but those are in the schema. Having the alternative HTTP feed adds completeness.

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

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

Schema coverage is 100%, so baseline 3 applies. The description adds meaning to type with an example ('sec_8k'), clarifies since as ISO timestamp, and explains the side effect of mark_read. Limit and unread_only are not described in the description but are well-documented in 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 'Pull fired events from your subscription feed,' which clearly identifies the action (pull), resource (subscription feed), and output (most recent alerts). It distinguishes itself from sibling tools like list_subscriptions and recent_changes by focusing on fired alert events with source, citation_uri, and payload.

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?

Clearly states filtering options (type, since) and polling behavior ('Polls work fine'). It also provides an alternative access method (GET registry.pipeworx.io/alerts.json) for scripts, which helps with when to use this tool versus other integration approaches, though it doesn't explicitly contrast with sibling tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds substantial behavioral context beyond annotations: the fan-out architecture (SEC EDGAR, GDELT→GNews fallback with rate-limit handling, USPTO soft-fail due to PatentsView API sunset), the return structure (changes[], total_changes, citation URIs), and the single parallel call nature. This fully discloses behavior without contradicting annotations.

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

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

The description is dense but well-organized: user-intent hooks, pipeline overview, parameter semantics, return format, and alternative tool. Every sentence earns its place, and the most crucial info (what it does) is front-loaded. 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?

Given the tool's complexity (multi-source fanout, fallbacks, soft-failures) and lack of an output schema, the description comprehensively covers all necessary context: what sources are queried, how fallback works, what the response looks like, and when to use an alternative. 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 coverage is 100%, but the description enriches parameter understanding by giving concrete examples ('2026-04-01', '7d', '30d', '3m', '1y'), clarifying relative shorthand, and recommending typical values. It also clarifies value can be ticker or CIK with examples. This exceeds the schema's baseline 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 explicit user-intent phrasings ('What's new with X', 'latest on Y') and a clear definition: 'change feed for a company in the last N days/weeks/months in ONE parallel call.' It clearly distinguishes from the sibling tool entity_profile, which is called out by name, making the tool's specific role unambiguous.

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

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

Provides explicit when-to-use guidance through user-intent examples and a direct alternative: 'Use entity_profile instead when you want the static profile... regardless of window.' Also gives practical parameter guidance ('Use "30d" or "1m" for typical monitoring'). This is exemplary usage differentiation.

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

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

While annotations indicate the tool is not read-only and is idempotent, the description adds valuable behavioral details: memory is scoped by the agent's identifier, and retention varies (persistent for authenticated users, 24 hours for anonymous). This goes beyond the structural annotations, though it doesn't mention overwrite behavior for existing keys.

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 and well-structured: the first sentence states the core function, the second provides usage context, and the third covers persistence and sibling tools. Every sentence earns its place, with 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?

For a simple two-parameter tool with no output schema, the description is complete. It covers purpose, usage, persistence, scoping, and integration with related tools, making it fully self-contained for an agent to decide when and how to invoke it.

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

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

The schema already fully describes both parameters with examples for key and value. The description reinforces this with usage examples and clarifies 'value' can be any text, but it doesn't add significant new semantic information beyond what the schema and its descriptions already provide. 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 saves data for later reuse across conversations or sessions, using 'Save' as the verb and specifying the resource. It distinguishes itself from siblings by explicitly naming recall and forget for retrieval and deletion, making its purpose unique.

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

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

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward'), with concrete examples like a resolved ticker or user preference. It also instructs pairing with recall and forget, which clarifies the intended workflow and 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 provide readOnlyHint=true and destructiveHint=false. The description adds behavioral context such as 'cascades through several lookup endpoints internally' and 'auto-disambiguated,' plus details about citation URIs. 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 moderately detailed but well-structured. It front-loads with trigger examples and the 'Use FIRST' directive, then breaks down supported types with specific output details. Every sentence conveys essential information without redundancy.

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

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

Despite no output schema, the description specifies exact return fields (e.g., ticker + 10-digit CIK + company_name for company; RxCUI + ingredient + brand for drug) and includes citation URIs. It also covers ambiguity handling and internal behavior, making it a comprehensive standalone description.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by specifying accepted input formats for company (ticker, CIK, or name) and drug (brand or generic), and mapping those to output fields. This adds value beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifier other tools require as input.' It differentiates from siblings with 'Use FIRST whenever you have a name but need an ID' and provides concrete trigger examples like 'What's the ticker for…' and 'find the CIK for…'.

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 given: 'Use FIRST whenever you have a name but need an ID.' It also implies it is a prerequisite for other tools and mentions it 'replaces 2-3 manual lookups,' making the when-to-use case 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 declare readOnlyHint, openWorldHint, and idempotentHint, covering the safety profile. The description adds meaningful behavior: it probes each entity with ai_visibility_check, ranks by score, surfaces most/least recognized, and returns a ranked list with score, confidence, and signal density per entity. This goes beyond annotations by explaining the aggregation and output structure.

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 efficient: two substantive sentences plus a brief example. It front-loads the core action, then explains the mechanism, use case, and return value without redundancy. Every clause adds information, making it compact 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?

For a tool with moderate complexity (multiple entities, optional models and API key, no output schema), the description provides sufficient context: it names the sub-tool called, the ranking behavior, and the return fields. It could go further by mentioning error handling or rate limits, but the essential behavioral contract is covered.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds valuable nuance by clarifying that the first entity is 'treated as the subject for narrative; rest are competitors', and uses 'your brand + N competitors' to align with the entities array. This supplements the schema definitions with usage context.

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

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

The description clearly identifies the specific verb 'Compare' and resource 'AI visibility across multiple entities side-by-side'. It distinguishes itself from the sibling ai_visibility_check by focusing on multi-entity comparison and adding ranking, making the purpose unmistakable.

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

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

The description states it is 'Useful for competitive AI-marketing audits' and gives a concrete example question, clearly indicating when to use it. It references ai_visibility_check as the underlying probe, implicitly signaling the alternative for single-entity checks, though it does not explicitly say 'use ai_visibility_check instead for one entity'.

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 (readOnly, openWorld, idempotent, non-destructive) by revealing the composite fan-out, partial failure grace, the 5-30s first-measurement delay for bundlephobia, and the sources_failed field. These are critical behavioral details not inferable from annotations alone. 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 relatively long (5 sentences) but every sentence provides essential information: purpose, trigger, return fields, ecosystem exclusion, and failure behavior. It is well-structured and front-loaded with the main purpose. It could not be trimmed without losing important context, but it is more wordy than strictly 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?

Despite having no output schema, the description lists all summary fields, mentions per-advisory details and links, provides source-specific caveats, explains the timeout and partial failure mode, and clarifies ecosystem scope. This is a complete picture for an agent to invoke the 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?

Schema description coverage is 100% and both parameters (package, version) are already clearly described in the schema. The description adds no significant new meaning about parameter formats or constraints; it only reinforces that the package is npm and version defaults to latest, all already stated in the schema. 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 opens with a specific composite action: "should I add this npm package to my project" check, and names the exact data sources (deps.dev and bundlephobia). It clearly distinguishes itself from sibling research tools by focusing on npm dependency evaluation and explicitly excludes other ecosystems. The verb and resource are crystal clear.

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

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

It provides explicit when-to-use guidance: "Use whenever an agent asks 'is X safe / popular / small' or 'what does adding lodash cost me'." It also gives an explicit alternative for non-npm ecosystems: "PyPI / Maven / Cargo / Go fall under deps.dev:version directly." This makes it easy for an agent to decide when to invoke this tool.

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

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

Annotations already indicate read-only/idempotent safety, but the description goes well beyond by disclosing the embedding model (BGE-base-en), the 500-char overlapping window approach, the 200K character cap, and truncation/flagging behavior. It also notes that every passage includes offsets for verbatim verification, which is critical for trust.

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 about 130 words, which is appropriate given the tool's complexity. Every sentence adds useful information: use case, benefit, pair tool, technical implementation, and limitation. The first sentence immediately states the core function, and the rest elaborates 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?

With no output schema, the description must convey return values, and it does: 'get back the top-N passages with character offsets and similarity scores.' It also covers input limits, truncation behavior, and the intended integration pattern. For a tool with 3 parameters and no output schema, this is fully 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, so the baseline is 3. The description adds value by providing a concrete query example, clarifying the text parameter's purpose ('text you already pulled'), and mentioning the cap/truncation details. This isn't a full re-description but meaningfully enhances 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 'Semantic search INSIDE a fetched record,' which is a specific verb + resource. It clearly distinguishes itself from siblings by focusing on searching within an already-fetched text, and even references ask_pipeworx_grounded as a companion tool.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also provides a pair pattern with ask_pipeworx_grounded and explains the benefit of context savings and verifiable citations. No exclusions are needed because it's a specialized helper.

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, including account requirements, inability to persist for anonymous/BYO, delivery channel specifics (feed always on, SMS verification and 10/day cap, webhook HMAC signing and auto-disable after 10 consecutive failures). There is no contradiction with the annotations; the readOnlyHint=false and idempotentHint=true are consistent with the described behavior.

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

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

The description is front-loaded with the main action and return value, then logically flows through prerequisites, types, and delivery options. It is dense with necessary details and each sentence earns its place, though the single-paragraph format could benefit from better structuring (e.g., bullets) for quick scanning.

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

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

For a complex tool with no output schema, the description is highly complete: it covers the return value (subscription id), prerequisites, type-specific parameter requirements, delivery channels and their constraints, and failure behaviors (webhook auto-disable). It also references sibling tools like recent_alerts and a public endpoint for consuming feed alerts, providing full context.

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

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

Although schema coverage is 100%, the description adds significant meaning beyond the schema by providing concrete examples for each type (e.g., sec_8k items codes, polymarket_edge topic, fred_series series_id) and operational constraints for delivery parameters (phone verification, 10/day cap, webhook secret behavior). These enrichments help the agent understand how to construct valid parameters.

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

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

The description clearly states the tool's purpose: 'Create a proactive monitoring subscription to a live-data event stream' and notes it returns the new subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation action and enumerating specific subscription types with examples.

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 the tool: to create a persistent subscription, with explicit prerequisites such as requiring a Pipeworx OAuth account and noting that anonymous/BYO cannot persist subscriptions. It also details delivery channel options and constraints, but does not explicitly mention alternatives like list_subscriptions or unsubscribe for 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?

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds transparency by explaining the output shape (category-bucketed examples with tool+argument shapes), the live catalog source, and that calling with no arguments returns the full spread while a topic focuses results. No contradictions with annotations.

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

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

The description is a single dense sentence, but it is well-structured with a list of example questions, followed by the return type and usage notes. It is long yet every clause adds information; could be broken into clearer sentences, but it is not wasteful.

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

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

Given the tool's onboarding purpose and no output schema, the description is complete: it explains what it returns, how to use it, when to use it, and the optional argument. It covers all necessary context for an agent to invoke it correctly.

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

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

The schema already covers the optional 'topic' parameter with a description and valid values. The description reinforces this by providing concrete examples ('finance', 'pharma', 'betting') and explaining that omitting it gives a cross-category spread, adding slight value beyond the schema.

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

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

The description clearly identifies the tool as the onboarding entry point for a newly connected agent, stating it returns category-bucketed example questions with exact tool and argument shapes. It uses specific verbs ('suggest_questions', 'returns') and resource ('what Pipeworx can do'), and it differentiates from siblings like ask_pipeworx and discover_tools by its focus on providing entry-level guidance.

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

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

It explicitly says 'Use this FIRST when you do not yet know what Pipeworx can do for you' and even mentions learning how to call meta-tools (ask_pipeworx, entity_profile, compare_entities). It also gives guidance on optional topic filtering, making when-to-use 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?

Beyond the annotations (destructiveHint=false, idempotentHint=true), the description explains the real-world consequence: the row is deactivated, not deleted, and historical events remain available via recent_alerts. This adds valuable context beyond the schema and annotations, giving the agent a clear picture of side effects.

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 tight sentences, front-loaded with the primary action. Every sentence earns its place: the first states the core operation, the second explains ownership and deactivation behavior. There is no redundancy or filler.

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

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

For a one-parameter tool with no output schema, the description is complete. It covers the action, the ownership constraint, and the side effect on recent_alerts. The annotations cover idempotency and destructiveness, and the schema covers the parameter. No critical information 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?

The schema description coverage is 100%, so the parameter 'id' is already well documented as 'Subscription id (uuid) returned by subscribe.' The description adds no further parameter-specific meaning beyond restating 'by id,' and the ownership constraint is a usage rule rather than a parameter semantic. 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 opens with a specific verb and resource: 'Cancel a subscription by id.' It clearly differentiates from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on cancellation. Additional details about ownership enforcement and deactivation further clarify the exact action.

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

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

The description provides clear context: ownership is enforced so you can only cancel your own subscriptions, and the row is deactivated rather than deleted. However, it does not explicitly mention alternatives or exclusions, such as 'use subscribe to create subscriptions' or 'you cannot cancel subscriptions you do not own.'

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 rich behavioral detail beyond annotations: it explains routing for financial vs. other claims, mentions verbatim evidence and judging, lists possible verdicts, and notes that it replaces multiple sequential calls. It is consistent with the readOnly, idempotent, openWorld, and non-destructive annotations, with no contradictions.

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

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

The description is longer than a simple one-liner, but it is information-dense and front-loaded with trigger examples. It covers usage, internal routing, return values, and efficiency claims without irrelevant fluff. A structured bullet list could improve scannability, but 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 tool's complexity, a 2-param schema with no output schema, the description is thorough. It explains input types via examples, the two processing paths, the exact return components (verdict, value, citation, reasoning), and what counts as a valid use case. It leaves minimal ambiguity for an agent deciding whether and how to invoke it.

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 references percent-delta math and tolerance handling, but the schema already fully documents claim and tolerance_pct with examples and defaults. The description adds minimal new parameter-level 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 performs natural-language claim verification, lists trigger phrases, and explains the veredict-based output. It differentiates by describing the structured SEC/XBRL path vs. the grounded fallback pipeline, distinguishing it from general Q&A or research 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 to use this tool whenever the agent needs to check whether something a user said is factually correct, and it delineates which claims use the structured path vs. the grounded pipeline. It does not name alternative sibling tools, but provides clear usage context and coverage boundaries.

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