Arcgis Onkaparinga

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

Beyond the readOnly/annotations, the description adds critical behavior: default model (Workers AI Llama-3.3-70b, free), optional Anthropic probing with a BYO API key and direct billing, and exact return fields (per-model score, confidence, signals, raw_response + combined view). This gives the agent a thorough understanding of side effects (costs for Anthropic calls) and output shape, which is not available in annotations or schema.

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

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

Three sentences, front-loaded with the core purpose. Each sentence earns its place: purpose + default model/API key + return structure + use cases. No filler, redundant phrasing, or unnecessary 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?

The description fully compensates for the missing output schema by specifying the exact return fields. It covers both operational modes (default vs Anthropic), cost implications, optional context parameter, and expected use cases. For a tool with 4 params and no output schema, this is complete and actionable.

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

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

Schema covers 100% of parameters, so baseline is 3. The description adds valuable semantic context: it clarifies the default model when 'models' is omitted and explains that '_apiKey' is passed through to Anthropic with direct billing. This goes beyond the schema's generic description, enriching the meaning of those 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 probes one or more LLMs about an entity and scores visibility 0-100 per model. It uses specific verb 'probe', names the resource (LLMs), and specifies the output (visibility score). It distinguishes itself from siblings by focusing on LLM knowledge and generic brand/topic coverage, versus competitor-specific tools like scan_competitor_ai_presence.

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

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

The description explicitly lists use cases: AI-marketing audits, pre-launch brand checks, competitive monitoring, which gives clear guidance on when to use it. It does not mention alternative sibling tools or when not to use it, but the context is clear and sufficient 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?

The description adds substantive behavioral context beyond annotations: it routes the question to a curated set of tools, fills arguments automatically, and returns a structured answer with stable pipeworx:// citation URIs. This clarifies what the agent should expect after invocation. The readOnly, idempotent, and non-destructive annotations are not contradicted by the description.

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 key instruction, and every section earns its place by expanding the domain list, trigger phrases, and citation behavior. It is long, but the length corresponds to broad usefulness. It could be trimmed slightly, so it does not quite achieve a 5, but nothing is wasted.

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

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

This is complete for a single-parameter factual querying tool with no output schema. The description covers when to use it, what it does, what kinds of inputs are valid, and what the answer will look like via structured answers and pipeworx:// citations. The annotations cover safety, and the schema covers parameters fully, so no critical context 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 description does not add much parameter-specific meaning, but it doesn't need to: the input schema already defines the single required parameter with a clear description and multiple aliases at 100% coverage. The description's examples reinforce that the parameter is a natural-language question, but that is already explicit in the schema, 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 clearly identifies a specific verb and resource: ask Pipeworx to answer factual questions using authoritative structured data and citations. It also explains the internal routing to 5,596 tools across 1,465 sources. However, it does not differentiate this tool from closely named siblings like ask_pipeworx_beta or ask_pipeworx_grounded, so sibling distinction is missing.

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

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

The description gives explicit WHEN to use: factual queries about current/historical data, specific trigger phrasings like 'look up', 'find', 'current', and examples. It also says to prefer this over web search and calls it 'START HERE'. It lacks explicit when-not-to-use guidance relative to the sibling Pipeworx variants, so it falls short of a 5.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable beyond-that context: this is explicitly a beta/experimental edge, routing improvements may appear live during tests, no candidate is active currently, and it is fully functional with no fallback. The warning about changing routing behavior is transparent and useful for an AI agent considering whether to use it.

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

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

The description is reasonably compact for the information it conveys, covering identity, experimental state, current behavior, and usage. It front-loads the key fact that it is the beta variant. A few extra details (retired candidate date) stretch the length slightly, but they support transparency without becoming verbose.

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 provides enough to understand this is the beta universal router and how to invoke it, and it points to the stable sibling for the full contract. There is no output schema, but the claim 'same response shape' appropriately signals that the existing ask_pipeworx output can be expected. It could be more robust by naming ask_pipeworx_grounded as a fully stable alternative, but that omission does not prevent correct invocation.

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

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

Schema coverage is 100% — all parameters are described in the input schema, including the aliases and their relation to the required 'question'. The description only says 'same arguments' without adding new semantics, so the baseline of 3 is appropriate.

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

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

The description clearly identifies this as the beta version of the ask_pipeworx universal router, matching the stable tool's 5,596 tools and response shape. It distinguishes itself from the stable variant by its experimental routing improvements. However, it relies on prior knowledge of what ask_pipeworx does and does not directly state 'answer questions by routing to tools' in plain terms.

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

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

It explicitly says to use this 'exactly like ask_pipeworx when you want the newest routing' and explains that results are compared against the stable router. It does not provide explicit 'do not use when' guidance, such as recommending the stable router for critical outcomes, but the experimental context makes the intended use reasonably 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 provide the read-only/idempotent safety profile, and the description adds valuable behavior beyond that: the extraction is restricted to ONLY the tool result, the exact success/refusal return shapes, the list of refusal_reason values, and the one-extra-LLM-call cost. This is genuinely transparent about failure modes and side effects. No contradiction with the annotations is present.

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 substantial but every sentence earns its place: purpose, routing mechanism, return contract, refusal reasons, use case, and cost comparison. The main purpose and key constraint are front-loaded in the first sentence. It is slightly detailed but appropriate for the complexity of a grounding/refusal tool.

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

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

Given the tool has no output schema, the description completely compensates by documenting both the success and refusal response shapes, refusal reasons, and performance/cost tradeoffs. It also names the sibling with the core behavioral difference. Nothing an agent needs to correctly invoke and interpret this tool is missing.

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

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

Schema coverage is 100% and all parameters are aliases for a single question string, so the schema already carries the semantic weight. The description adds meaning beyond the schema by explaining that the question drives cross-source routing, argument filling, and data fetching. This helps the agent use the question appropriately even though the schema already documents the field.

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 mode: a hallucination-resistant, grounded answer mode that picks a tool, fetches data, and extracts an answer only from the tool result. It explicitly distinguishes from sibling ask_pipeworx by the grounded/extraction behavior and high-stakes use. This makes the tool's purpose immediately identifiable.

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: any time the answer will be quoted, cited, or acted on and facts must not be invented. It also explicitly directs users to prefer ask_pipeworx for casual lookups, naming the alternative and the condition that selects it. This fully covers the usage selection decision.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: the resolver contract (market_match_confidence, alternatives), low-confidence short-circuit status, closed-market handling, illiquid wide-spread warnings, cancellation-rule parsing with ev_impact, and news fallback retry behavior. This greatly exceeds the annotation baseline.

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

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

The description is very long but densely packed with necessary behavioral contracts for a multi-branch tool. Uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, PARENT_EVENT, NEWS FIELDS, SAFETY, RESOLUTION-RULE RISK) make it scannable. Some redundancy exists (e.g., repeated mention of low-confidence paths), but overall the length is justified by 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 document return structure and edge cases, and it does so thoroughly. It explains response shapes, resolver confidence, parent_event extraction, news fallback fields, status codes (low_confidence_match, market_closed_or_inactive), and resolution-rule risk. For a tool with this inherent complexity, this is about as complete as a text description can get.

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 explaining accepted market formats (slug/URL/question text), the effect of 'depth' (quick vs thorough fan-out), and the response-size implications of include_raw ('keeps responses under ~20KB'). This extra context pushes it above baseline.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools like polymarket_edges and polymarket_arbitrage by focusing on data aggregation and evidence packets rather than pure edge calculations. It also states accepted input formats and typical use cases ('should I bet on X').

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

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

The description gives explicit usage scenarios ('Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"') and many fan-out examples that illustrate when each category applies. It does not explicitly name alternatives or state when *not* to use the tool, but the contextual guidance is strong. This matches 'clear context, no exclusions'.

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

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

Annotations already declare readOnly/openWorld/idempotent, and the description adds valuable context: data sources (SEC EDGAR/XBRL, FAERS), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs in responses. 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 every sentence adds value: trigger phrases, preference rule, data source details, and response format. It is front-loaded with the tool's purpose and usage, though slightly long, it avoids fluff.

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

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

Covers both entity types, data sources, edge cases (off-calendar fiscal years), sorting behavior, output format (paired data + citation URIs), and efficiency benefits. Since there is no output schema, the description compensates by explaining return contents adequately.

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

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

The input schema has 100% parameter coverage with descriptions, but the tool description adds meaningful semantics beyond that, such as the specific financial metrics pulled for companies (revenue, net income, cash, long-term debt) and drug-specific counts (FAERS events, FDA approvals, active trials). This enhances parameter understanding significantly.

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 side-by-side comparison of 2–5 companies or drugs in a single parallel call. It provides concrete trigger phrase examples and distinguishes itself from sequential single-pack lookups by explicitly preferring this tool for comparisons.

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

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

The description explicitly states when to use this tool ('when comparing entities') and instructs 'ALWAYS PREFER over sequential single-pack lookups'. It also gives alternative behavior (sequential lookups) and clarifies usage by entity type, making the usage guidance highly actionable.

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 safety profile is already covered by annotations (readOnlyHint, idempotentHint, openWorldHint, destructiveHint:false), and the description adds real behavioral context: gaps[] are only ever explicit, never invented; contradictions[] appear on standard/thorough; citation_uri is only present when known to be resolvable via resources/read; records are semantically excerpted, not head-truncated; latency is bounded as 15-60s (up to ~90s for thorough). 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 front-loaded and every paragraph concept holds information, but it is clearly overlong: the ask_pipeworx alternative is given at least three times (sign-in gate, single lookup, breaking news), depth iteration details overlap the schema's per-enum description, and the middle contains dense run-on sentences. Effective density-wise, but it wastes agent tokens through 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?

There is no output schema, so the description carries the burden of explaining return value, and it mostly succeeds: findings packet shape (verbatim evidence + confidence + source + fetched_at), stable citations, the gaps[] contract, contradiction[] behavior by depth, and latency expectations are all covered. It loses a point because the later hop-by-hop iteration text is muddled and slightly ambiguous about which depth triggers which pass.

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 both params already carry rich descriptions (question = natural language, decompirable; depth = enum with per-hops behavior). The description adds value beyond the schema: 'thorough' is paid, quick is a single hop, standard adds a gap-recovery hop, and thorough adds the contradiction[] scan plus latency per depth. Some of this overlaps the schema enum text, so it's 4 rather than 5.

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

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

The description states a specific verb+resource combo: 'Grounded multi-source research across Pipeworx's 165 STRUCTURED data sources... in ONE call', and explicitly disclaims what it is not ('this is NOT open-web search'). It also explains the facet-decomposition and parallel-routing mechanism, so an agent can distinguish it from ask_pipeworx and the other 34 siblings without opening the schema.

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

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

Usage context is explicit and prescriptive: 'Best for broad/multi-part questions over structured data', 'For a single lookup use ask_pipeworx instead', 'If you are not signed in, use ask_pipeworx', and it notes the paid tier gate for depth:thorough. These are concrete when/when-not rules with named alternatives, not just implied 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?

Annotations already mark it as read-only, idempotent, and non-destructive. The description adds valuable behavioral detail: it returns top-N tools with names, descriptions, and full input schemas, and says results are ready to call directly without a second schema lookup. This makes runtime behavior and output structure concrete.

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

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

Three sentences: purpose, usage, and output/behavior. The domain enumeration is slightly long but useful, and no filler is present. Front-loaded with the primary action.

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

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

No output schema exists, so the description carries the burden of explaining return values; it does so clearly ('top-N most relevant tools with names, descriptions, and full input schemas') and notes direct callability. It also contextualizes how to start a multi-tool session, making it self-sufficient for selecting and 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?

Input schema gives full descriptions for all six parameters (100% coverage), including aliases and limit constraints, so the description doesn't need to repeat them. The phrase 'describing the data or task' mirrors the query semantics, but adds no new parameter-level insight beyond the schema. 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 'Find tools by describing the data or task,' clearly identifying it as a tool-discovery endpoint. It enumerates covered domains and distinguishes itself from siblings by returning tool schemas rather than data, aligning with its title/name.

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 ('when you need to browse, search, look up, or discover what tools exist') and gives a strong directive: 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This implies when you already know the tool, use it directly, providing clear usage heuristics.

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 substantial behavioral context beyond annotations: it fans out across multiple sources, returns specific fields, notes the USPTO PatentsView API sunset and soft-fail behavior, and describes the GDELT→GNews fallback chain. 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 long but well-structured and front-loaded with trigger phrases, then purpose, then detailed return breakdown, and input constraints. Every sentence contributes value, though it could be marginally tightened without losing key 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?

With no output schema, the description fully compensates by detailing every return component (cik, filings with URIs, fundamentals, patents, news, LEI) and its specifics (up to 5 filings, LATEST 10-K fields, soft-fail, fallback chain). Input constraints and alternatives are also covered, making it complete for this tool's complexity.

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

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

The input schema already has 100% coverage with descriptions for both parameters (type enum and value format). The description repeats this information (ticker/CIK, names not supported) without adding new meaning, so the baseline 3 is appropriate.

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

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

The description clearly states it creates a full cross-source profile of a US public company, with multiple user-intent examples. It distinguishes itself from siblings like compare_entities and resolve_entity by emphasizing its holistic, single-call nature and explicit preference over chaining single-pack lookups.

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

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

Explicitly provides when-to-use guidance: "ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view." It also names an alternative for names not supported: "use resolve_entity first if you only have a name." This is clear and actionable.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Delete' aligns with those. It adds useful context about clearing sensitive data and relationship to remember/recall, going beyond the annotations without contradicting them.

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

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

Three short sentences, each earning its place: purpose, usage guidance, and tool relationships. No redundant or filler 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?

Given the tool's simplicity (one required parameter, no output schema), the description combined with annotations covers purpose, usage, safety, and parameter meaning. Nothing essential is missing.

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

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

Schema coverage is 100%: the 'key' parameter is described as 'Memory key to delete.' The description's 'by key' merely confirms the schema. It adds no new semantic detail about the parameter beyond what the schema already states, 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 'Delete a previously stored memory by key,' using a specific verb and resource. It distinguishes forget from sibling tools like remember and recall by explicitly framing it as the deletion counterpart.

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: 'when context is stale, the task is done, or you want to clear sensitive data.' It also names alternatives and companions ('Pair with remember and recall'), giving clear context relative to siblings.

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

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

The description adds behavioral detail beyond the readOnlyHint and idempotentHint annotations: it fetches the page, extracts specific elements (title/description/key links), and outputs a single text blob. It does not mention error handling or edge cases, but given the strong annotation coverage, the added context about the fetch-and-extract behavior is valuable. 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 four sentences, front-loaded with the core action and process, followed by output format and use cases. Every sentence adds value: purpose, process, output, and use cases. There is no fluff or redundancy, making it efficient and well-structured.

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

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

For a simple tool with two parameters, no nested objects, and no output schema, the description covers the primary context: what it does, how it works, output format, and typical use cases. It lacks edge-case details (e.g., invalid URLs, rate limits), but these are not critical for this low-complexity, read-only tool, making it reasonably complete.

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

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

Schema description coverage is 100% for both parameters (url and max_links), so the schema already fully documents them. The description does not add meaning beyond what the schema provides, except implicitly through the 'single text blob' output statement, which relates to max_links behavior. This is the baseline 3 for high schema coverage.

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

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

The description clearly states the tool's function: 'Generate a production-ready llms.txt file for any URL' and explains the process (fetches page, extracts title/description/key links, emits markdown). It distinguishes itself from siblings by focusing specifically on generating the llms.txt standard format, unlike related tools like scan_competitor_ai_presence or ai_visibility_check.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' It gives context for when to use it, though it does not explicitly state exclusions or alternative tools. This is a clear context without exclusions, matching a 4.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context by detailing exactly what information the tool returns (fields with name/type, geometry type, record count, capabilities), which goes 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 a single, front-loaded sentence with no filler. Every phrase adds meaningful information, 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?

For a simple one-parameter tool with no output schema, the description adequately covers the tool's purpose and return contents. The annotations provide safety context, and the description lists the key outputs, making it fully complete 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?

The input schema provides 100% coverage for the single 'url' parameter with a clear description and an example. The tool description only repeats 'by url' and does not add extra semantics, so the baseline of 3 applies.

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

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

The description uses a specific verb ('Get'), names the resource ('ArcGIS Feature/Map Service layer's schema'), and lists concrete contents ('fields, geometry type, record count, capabilities'). This clearly distinguishes it from sibling tool 'query_layer', which would be for retrieving data rather than schema.

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 use when you need schema metadata for a layer, and the inclusion of 'by url' conveys the input requirement. However, it does not explicitly mention when not to use it or reference alternatives like 'query_layer', so it lacks explicit exclusions.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds useful context by scoping to 'the caller's' subscriptions, noting that only active subscriptions are listed by default, and disclosing the return fields. 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 three sentences, front-loaded with the core purpose, followed by return fields and a practical usage tip. Every sentence earns its place with no redundant or promotional language.

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

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

For a simple tool with one optional parameter and no output schema, the description is complete. It states what the tool does, what it returns, and when to use it. The lack of an output schema is compensated by explicitly listing the returned fields, making the tool fully understandable.

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

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

The schema fully describes the single optional parameter (include_inactive) with a clear description. The tool description adds little to parameter understanding, only implying that 'active' is the default and that cancellations are inactive. With 100% schema coverage, 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 identifies the tool as listing the caller's active subscriptions, a specific verb+resource that is distinct from sibling tools like subscribe and unsubscribe. It further clarifies what is returned (id, type, params, timestamps, fire count), leaving no ambiguity about the tool's function.

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

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

The description provides explicit use cases: 'review what you're monitoring before adding more' and 'find an id to cancel.' This gives clear context for when to use the tool, though it does not explicitly name alternatives or say when not to use it. Sibling tools like subscribe/unsubscribe make the distinction implicit.

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

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

Annotations only indicate readOnly=false, destructive=false, etc., giving little safety context. The description fills this gap richly: it discloses rate-limiting ('5 per identifier per day'), that it's free and doesn't count against tool-call quota, that filing without an account returns a claim_token, and that responses to claim_token indicate status and changes. It also states the feedback is read daily and affects roadmap. This goes well beyond annotation 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 longer than average but every sentence carries functional value. It is front-loaded with the core purpose, then systematically covers scope, usage boundaries, workflow, expectations, and constraints. It could be tightened slightly (e.g., the 'Not sure?' qualifier is a bit redundant with the earlier boundary note), but overall it earns its length.

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

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

Given the tool has 4 parameters with a nested object, no output schema, and no direct return docs, the description is exceptionally thorough. It covers the return mechanism (claim_token), rate limits, scope, and appropriate content. It explains the tool's integration with the broader Pipeworx ecosystem (digests, roadmap). This is a genuinely complete description for a feedback channel.

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

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

Schema description coverage is 100%, so the schema fully documents each parameter, meeting the baseline of 3. The description adds value beyond schema by explaining the claim_token usage pattern ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), clarifying the 'message' scope (describe in terms of Pipeworx tools, not user prompts), and noting no parameters are required. This pushes it to 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 clear verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It explicitly lists feedback categories (bug, feature, data_gap, praise), making its purpose unambiguous. It also distinguishes itself from siblings by focusing solely on feedback about Pipeworx tools, not on asking questions or research.

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

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

The description explicitly states when to use the tool (for broken/stale data, missing tools, data gaps, or praise) and when not to use it (for tools from other MCP servers). It even provides a heuristic: 'Pipeworx tool names are the ones this connection lists.' It also explains the claim_token workflow for checking resolution status, giving clear situational usage guidance.

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

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

Adds valuable context beyond annotations: data derived from CF analytics-engine, no PII, aggregation nature, and caching behavior (5min-1h depending on window). This informs the agent about freshness and privacy without contradicting the read-only 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?

Well-structured and front-loaded with the core purpose. The 'Useful for' list is organized and every sentence adds value. Not overly verbose despite being detailed.

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

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

Despite no output schema, the description explains what is returned (top tools, packs, call volume, and the tuple format) plus data source and caching. Adequate for an agent to understand expected output and behavior.

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

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

Schema coverage is 100% and the description repeats the same window explanation already present in the schema. No new semantic information is added about the parameter.

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

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

The description clearly states what the tool does: it shows what other AI agents are calling on Pipeworx, returning top tools, packs, and call volume over a window. This is specific and distinguishable from sibling tools like discover_tools or search_datasets.

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 'Useful for' scenarios with three concrete use cases, and explains how different windows serve different needs (hot right now vs steady-state). This gives clear guidance on when to use the 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 readOnly/openWorld/idempotent annotations, the description reveals rich behavioral details: the >3pp threshold for partition_check, the ≥0.30 Jaccard semantic anchor, the >20% placeholder fraction filter, the fill check against live CLOB depth, and the rule 'realizable_edge_pp ≤ 0 means do not trade it.' It also describes the response structure and edge-case handling.

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 informative, but it is a single long paragraph that could be better organized with bullets or section breaks. It front-loads the core purpose, and every sentence adds value given the tool's complexity, but readability suffers slightly from the lack of structure.

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 compensates by specifying the response fields (opportunities[], gap_pp, partition_check, etc.). It also covers edge cases (placeholder filters, low similarity), the fill-check workflow, and cross-references for custom sizing. For a complex tool with two modes and many behavioral nuances, this description is exceptionally complete.

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

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

Schema coverage is 100%, but the description adds significant meaning: it provides concrete examples for both parameters ('fed-decision-may-2026', 'Strait of Hormuz traffic returns to normal'), explains parameter-specific behavior (event walks child markets; topic flattens union across events), and clarifies that calling with no args triggers trending_scan—a detail not 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 a specific verb+resource+mechanism: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes three invocation modes (no-arg trending_scan, event, topic) and references polymarket_fill_risk for custom sizing, differentiating it from that sibling.

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

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

The description gives explicit when-to-use guidance: it recommends `event` for a specific market, `topic` for cross-event scanning, and notes the no-arg default for trending scan. It also states when to use a different tool ('For custom sizing use polymarket_fill_risk'), covering 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 goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint). It discloses caching behavior ('Cached 1h at the KV level keyed on all knobs'), the exclusion of Fed bets from ranking due to unreliable signal, the 'Market moved X.Xpp in 24h' warning, the design of partition_overround returning kelly_fraction_half=0 at parent level, and the rare-by-design nature of concentrated_longshot. These are critical behavioral traits not captured by annotations, providing exceptional transparency.

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

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

The description is extremely long and dense, functioning more like a full specification than a concise tool description. While it is well-structured with clear sections for model families, knobs, and response format, its length could overwhelm an agent and dilute focus. Every sentence carries information, but the overall size is not 'appropriately sized' for quick consumption. It earns a middle score for structural organization despite lacking conciseness.

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

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

Given the tool's complexity and the absence of an output schema, the description is remarkably complete. It describes the top-level response structure (by_segment, fed_candidates/fed_note, _diagnostics), the content of each segment (edge_pp_net, kelly_fraction, liquidity, spread, volume, 24h warning), and the expected behavior of all knobs. It even provides rationale for exclusions and diagnostic usage, leaving no major gaps for an agent to invoke and interpret results correctly.

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

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

Although schema coverage is 100%, the description adds substantial meaning to parameters. It explains the 'TRADEABLE-EDGE KNOBS' (min_liquidity, max_spread_pp, min_partition_leg_kelly) and clarifies an important nuance: min_kelly never filters partition arbs because they return parent-level kelly_fraction_half=0, and min_partition_leg_kelly applies per-leg instead. It also gives context for slippage_pp with real-world reasoning about Polymarket fees. These enrich the schema descriptions significantly.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It specifies the resource (Polymarket markets), the verb (scan/return), and the specific value proposition (opportunities from Pipeworx disagreement). It also distinguishes from likely siblings by focusing on 'what should I bet on today' discovery rather than arbitration or tracking, making it clearly differentiated.

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 this tool: it's built for 'what should I bet on today' and helps agents 'discover opportunities without paging hundreds of markets.' It also gives guidance on parameter knobs (e.g., min_liquidity to drop thin-book opportunities). However, it doesn't explicitly mention when not to use it or compare with alternatives like polymarket_arbitrage or polymarket_edge_tracker, so it lacks explicit exclusions but still offers strong contextual guidance.

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

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

Beyond the readOnly/idempotent annotations, the description discloses how snapshots are written on cache-miss, that gaps mean no scan, the 60-day TTL bound, and that decay uses daily closes not intraday. It also explains the sign convention for edge_pp_net, giving rich behavior context.

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

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

The description is organized into Args, RESPONSE, and LIMITS sections, leading with the core purpose. Every sentence adds essential value, making the length justified for a complex tool without an output schema.

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 compensates by detailing the response structure (tracked, expired, snapshot_dates), field-level semantics, and data limitations, providing a complete operational picture for an agent.

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

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

Schema coverage is 100% with parameter descriptions for days and window. The tool description restates defaults and the window family, adding no significant new semantic meaning beyond what the schema already provides.

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

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

The description clearly states the tool provides 'edge persistence and decay telemetry' built from daily snapshots, and explicitly contrasts fresh versus old edges, distinguishing it from sibling polymarket_edges which likely focuses on current edges.

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

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

It gives clear context: use this when you need to know how long an edge has existed and whether it is shrinking, and mentions the 'competition clock' for lifespan. However, it does not explicitly name alternatives or state when not to use it, though the reference to polymarket_edges snapshots implies a contrast.

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

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

Although annotations already declare readOnly/openWorld/idempotent/non-destructive, the description adds substantial behavioral context: ladder-walking, verdict outcomes (clean/degraded/cannot_fill), basket capture mechanics, forced_directional_risk, and the risk of partial fills. 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 appropriately so given the tool's complexity. It is front-loaded with the core purpose, then clearly organized into SINGLE-MARKET and BASKET sections, with every sentence carrying substantive information and no filler.

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

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

With no output schema, the description enumerates return fields such as `top_of_book`, `vwap_fill_price`, `slippage_pp`, `capture_ratio`, `thin_legs[]`, and `forced_directional_risk`, and explains failure modes. It provides enough detail for an agent to invoke the tool correctly and interpret results.

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

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

Schema coverage is 100%, and the description adds rich meaning beyond the schema: mode-specific interpretations of `side`, `size_usd` as spend vs target proceeds vs settlement notional, default values, clamps, and how `market` vs `event` selects the mode. This fully disambiguates all four 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 opens with a specific purpose—'Realizable-vs-theoretical edge check against live CLOB order-book depth'—making the tool's function clear. It also distinguishes single-market and basket modes, and explicitly ties its use to polymarket_arbitrage and polymarket_edges signals, differentiating it from siblings.

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

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

The description explicitly states when to use the tool: '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 partial basket fills create unhedged risk—giving a clear threshold and exclusion.

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

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

Annotations already declare read-only/idempotent, but the description goes much further: it details compatibility_warning trigger cases, temporal_alignment semantics ('aligned:false means spreads are mathematically meaningless'), and skipped_cross_type counters. This gives the agent clear expectations about edge cases and safety behavior.

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

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

The description is long but deliberately structured: purpose, modes, response, safety fields, caveat. It front-loads the core function and each subsequent sentence adds operational context; no filler, though dense enough that bullets would help readability.

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

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

With no output schema, the description compensates by explaining the response components: leg-by-leg prices, matched spread[].top_spreads_pp, compatibility_warning, temporal_alignment, and skipped counters. It also warns about false positives, making it robust for an agent 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 is already 100% covered with parameter descriptions and enum-ish topic values, so baseline is 3. The description adds meaningful mode behavior, auto-fetch semantics, and explicit override behavior (e.g., 'Overrides the topic-mapped side') 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 opening sentence defines a specific cross-venue spread between two named platforms and explicitly ties it to the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by emphasizing same-question comparison and compatibility detection.

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 lays out two modes (pre-mapped topic vs explicit ticker/slug) and tells the user when the delta is a real signal vs when the tool reports incompatibility. It includes caveats like 'pre-mapped ≠ tradeable' and that most shortcuts return compatibility_warning today, though it doesn't name alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that it 'Returns attribute rows (and geometry)' and suggests a sampling idiom, which gives useful behavioral context beyond the structured annotations. No contradictions found.

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

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

The description is two concise sentences that front-load the core action. Every phrase earns its place — the action, the parameter list, the return type, and the sampling tip. No redundant or marketing language.

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

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

The tool has 6 parameters (all documented in schema) and no output schema, but the description covers the return format (attribute rows and geometry) and provides a usage pattern. It does not mention error handling or authentication, but given the read-only, idempotent nature and the schema richness, it is sufficiently complete for most use cases.

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

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

With 100% schema description coverage, the baseline is 3. The description adds value by qualifying `where` as 'SQL-like', `out_fields` as 'comma-separated', and providing a concrete example of combining parameters for sampling. This goes beyond simply listing parameter names.

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

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

The description opens with 'Query an ArcGIS Feature Service / Map Service layer by its url' — a specific verb and resource. It also references 'search_datasets' as the source of the URL, effectively distinguishing this query tool from sibling tools like layer_info or search_within. The list of query parameters further clarifies its purpose.

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

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

The description provides clear usage context: it is meant to query layers obtained from search_datasets, and the tip 'Use where="1=1" + out_fields="*" to sample' gives concrete guidance. It does not explicitly name alternatives or when not to use it, but the context and sampling tip are sufficient for standard usage.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context beyond this: it is scoped to a user identifier (anonymous IP, BYO key hash, or account ID) and mentions the list-all-keys behavior when the key is omitted. No contradictions with annotations.

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

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

Three sentences, front-loaded with the core action (retrieve/list), followed by usage context and scoping. Every sentence earns its place; no fluff or redundancy beyond what is necessary for a clear, complete description.

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

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

The tool is simple (one optional parameter, no output schema), and the description explains both return modes: a single value or a list of keys. It also covers scoping and pairs with sibling tools. Combined with thorough annotations, this is complete for a retrieval 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 baseline is 3. The description repeats the optional-key/omit-to-list behavior already in the schema property description, and only adds illustrative examples of key contents (e.g., target ticker, address). This is marginal added value, not substantial new semantics.

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

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

The description uses a specific verb and resource: 'Retrieve a value previously saved via remember, or list all saved keys.' It clearly distinguishes the tool from siblings by explicitly referencing remember and forget, and it provides a concrete scope (user's target ticker, address, research notes).

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

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

The description explicitly states when to use the tool: 'Use to look up context the agent stored earlier... without re-deriving it from scratch.' It also gives directional guidance by pairing with 'remember to save, forget to delete,' which serves as an alternative/contrast.

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

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

Annotations declare readOnlyHint=true, but the description states mark_read:true flags returned events read, which changes state. This directly contradicts the read-only hint, earning a score of 1 per the contradiction rule.

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

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

Four sentences, each with a distinct purpose: main action, return payload, filtering options, and side-effect/alternative access. It is front-loaded and free of fluff, making it efficient and well-structured.

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

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

With no output schema, the description compensates by naming return fields (source, citation_uri, raw payload) and explaining filters and mark_read behavior. It does not mention unread_only or limit explicitly, but the full schema covers these, so it is reasonably complete for a read tool with rich annotations.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by giving a concrete example for type ("sec_8k") and explaining mark_read's effect on future calls, enriching the schema descriptions without repeating them.

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

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

The description clearly states the tool pulls fired events from the subscription feed and returns recent alerts, with a specific verb and resource. It naturally distinguishes from siblings like recent_changes by focusing on subscription alerts and their 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?

Gives clear context: mentions polling works fine and points to an HTTP endpoint for scripts/dashboards, implying the tool is for interactive use. Does not explicitly name sibling alternatives, but provides practical usage guidance without excluding contexts.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is known. The description goes far beyond by disclosing the fan-out to SEC EDGAR, GDELT→GNews fallback behavior, USPTO PatentsView sunset soft-fail, accepted date formats, and output structure. This is exemplary behavioral transparency.

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

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

The description is dense but every sentence carries meaningful content: usages, source fallbacks, parameter specifics, return shape, and an alternative tool pointer. It is front-loaded with natural-language triggers and has no fluff, making it well-structured for quick comprehension.

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 explicitly listing the return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs) and documenting edge cases like API failures and sunset dates. For a 3-parameter tool with complex external-source behavior, this description is remarkably complete.

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

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

Schema coverage is 100% and the schema already fully describes each parameter, including `since` examples and `value` ticker/CIK formats. The description mostly repeats these details, adding little new parameter-specific meaning, though it reinforces the window concept and parallel execution. Baseline 3 is appropriate since the schema handles the heavy lifting.

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

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

The description clearly states the tool provides a change feed for a company over a recent window, with explicit natural-language triggers ("What's new with X") and a specific verb+resource combination. It also distinguishes itself from the sibling tool entity_profile, making its purpose unambiguous.

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

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

The description provides explicit usage guidance: it lists query phrasings, specifies the tool is for recent changes in a time window, and directly says to use entity_profile instead when the static profile is needed. This gives clear when-to-use and when-not-to-use guidance, fully addressing alternatives.

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

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

Beyond annotations (idempotent, non-destructive), the description discloses key behavioral traits: key-value pair scoped by identifier, 24-hour retention for anonymous sessions, and pairing with recall/forget. It does not contradiction annotations; the idempotent hint aligns with overwriting behavior, though overwrite is not explicitly stated.

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 but every sentence adds value: purpose, usage context, persistence scoping, and companion tools. It is front-loaded with the primary action and avoids redundancy, though it could be slightly more concise.

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

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

For a simple 2-param tool with no output schema, the description covers the essential context: persistence, auth differences, and integration with recall/forget. It does not mention limits (e.g., key length, value size) but these are likely non-critical; overall it is sufficiently complete.

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

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

Schema coverage is 100%, with both key and value parameters already described with examples. The description adds no new parameter details beyond confirming 'key-value pair', so the baseline of 3 applies.

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

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

The description clearly states it saves data for reuse across conversations or sessions, with a specific verb ('save') and resource ('data'). It distinguishes itself from sibling tools by naming 'recall' and 'forget' as companions, making its role in the memory system 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?

Provides concrete 'when to use' guidance with examples (resolved ticker, target address, user preference) and explains persistence differences for authenticated vs anonymous users. It lacks an explicit 'when not to use' clause, but the context strongly implies it for non-persistent or fresh lookup needs.

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 non-destructive behavior, but the description adds valuable behavioral context beyond that: internal cascading lookups, graceful degradation if GLEIF/OpenFIGI is unavailable, and explicit reporting of unresolved identifiers. These details meaningfully inform the agent about edge cases and robustness.

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 comprehensive but verbose, packed into a single dense paragraph. It is front-loaded with purpose and usage, but contains extra detail that could be trimmed (e.g., 'using resolve_entity replaces 2-3 manual lookups', long ISIN explanation). It is not a model of conciseness, though it remains organized and readable.

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

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

With no output schema, the description must compensate for return-value semantics, and it does: it mentions identifier source labelling, an `unresolved` field, fallback behavior, and the types of IDs returned for each entity type. It also situates the tool relative to sibling tools ('other tools require as input') and gives clear usage priority. This is sufficient for a complex lookup tool.

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

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

Schema coverage is 100% and both parameters are described in the schema, so baseline is 3. The description raises this by adding nuance: for company type it explains ticker/CIK/ISIN/name inputs and the ISIN-to-LEI mapping, and for drug type it clarifies brand/generic name handling. This goes beyond simple schema repetition.

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

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

The description clearly defines the tool's purpose: resolving a user-spoken name to canonical/official identifiers. It uses a specific verb ('resolve') and resource ('entity'), and distinguishes itself from sibling tools by emphasizing ID lookup as a prerequisite for other tools. The opening examples ('What's the ticker for...', 'find the CIK for...') immediately convey scope.

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

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

The description gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' This provides clear when-to-use context. It does not explicitly name alternatives or exclusions, but the supported types and examples imply the boundaries well enough.

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

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

Annotations already indicate a read-only, idempotent, non-destructive operation. The description adds behavior beyond that: it states that each entity is probed with ai_visibility_check, results are ranked, and it surfaces most/least recognized entities. It also discloses the return fields (score, confidence, signal density). This is valuable context 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?

Three sentences, front-loaded with the core purpose, followed by mechanism, use case, and output. Every sentence adds distinct information with no filler or redundancy.

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

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

Despite having no output schema, the description specifies the return format (ranked list with score, confidence, signal density). It provides a concrete use case and indicates the tool is for multi-entity comparison. Minor gaps: it doesn't mention entity count limits or model-specific requirements, but these are covered in the schema, so overall completeness is good.

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

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

Schema description coverage is 100%, so the schema already documents all parameters (entities, models, _apiKey, context). The description adds only a slight reinterpretation of 'entities' as 'your brand + N competitors', but schema already notes the first entry is the subject. No meaningful additional semantics are provided beyond the schema.

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

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

The description states a specific action (compare), a clear resource (AI visibility), and a scope (multiple entities), and distinguishes itself from sibling ai_visibility_check by explicitly mentioning probing each entity and ranking side-by-side. It also specifies output (ranked list with score, confidence, signal density), making the 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 gives a clear use case: competitive AI-marketing audits, with an example question ('does Claude know about us as well as our competitors?'). It implies this is the multi-entity variant of ai_visibility_check, but does not explicitly mention alternatives or when not to use it, 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?

The description adds substantial behavioral context beyond the readOnly/idempotent annotations: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, sources_failed lists timeouts, and the tool is NPM-only in v1 with ecosystem-specific fallbacks. 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 well-organized: purpose, use cases, return fields, limitations, and failure behavior are each covered in a tight, front-loaded manner. Every sentence adds value without redundancy.

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

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

Given the tool's complexity (composite of two external APIs, no output schema), the description is remarkably complete: it lists the exact summary fields returned, notes partial failure modes, and clarifies scope (NPM vs other ecosystems). No significant gaps.

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

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

Schema coverage is 100%, so the baseline is 3. The description does not add additional semantics for the 'package' or 'version' parameters beyond what the schema already provides (e.g., scoped packages accepted, default version). It focuses on return behavior instead.

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

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

The description clearly defines the tool as a composite 'should I add this npm package to my project' check, stating it fans out across deps.dev and bundlephobia. It distinguishes itself from sibling tools by targeting npm dependency safety and size concerns specifically.

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

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

Explicitly says 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"' and provides a clear alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly.' This gives both when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds value by disclosing the return fields (name, summary, record_count, owner/org, url) and how to use the result, which goes 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 a single, well-structured sentence that front-loads the action, includes the resource scope, and conveys return details and downstream usage. Every clause earns its place with 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 lacking an output schema, the description clearly enumerates the return fields and gives actionable downstream guidance. It does not mention error behavior, pagination, or the open-world nature of results, but given the annotations and schema, it is sufficiently complete for a search tool.

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

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

The input schema covers all three parameters with descriptions (query, limit, org_id), giving 100% coverage. The description reinforces that search is by keyword but adds no new parameter-level semantics beyond the schema, 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 tool searches City of Onkaparinga GIS open geospatial datasets by keyword, with a specific resource and action. It also distinguishes from siblings by noting the returned Feature Service url should be passed to query_layer/layer_info, which clarifies its unique role.

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

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

The description provides clear context for use (searching datasets by keyword) and explicitly points to downstream tools (query_layer/layer_info) for further action. However, it does not explicitly state when not to use this tool or contrast it against other search tools, so it lacks full exclusionary guidance.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the embedding model, windowing approach, return format (passages with offsets and scores), and the 200K character cap with truncation flagging. This provides substantial behavioral context.

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

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

The description is dense but every sentence adds value: purpose, use case, output, verification benefit, pairing with sibling, and technical constraints. It is well-structured and front-loaded with the core action.

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

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

With no output schema, the description adequately explains the return format (top-N passages with offsets and similarity scores). It covers performance considerations (truncation, windowing) and fits the tool within the broader workflow, making it complete for the given complexity.

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

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

Schema coverage is 100%, so parameters are already documented. The description adds semantic context by explaining 'text' as the previously fetched record, giving natural-language query examples, and clarifying the limit's default (5) and range (1-20), which enhances understanding beyond the schema.

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

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

The description clearly states it performs 'Semantic search INSIDE a fetched record', specifying the verb and resource. It distinguishes itself from siblings by emphasizing it operates on already-pulled text and by referencing the complementary relationship with ask_pipeworx_grounded.

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

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

Explicit guidance is given: 'Use when the record is too big to cram into the prompt'. It also explains the workflow pairing with ask_pipeworx_grounded, offering a clear alternative strategy for handling large documents.

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 write, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond that: subscriptions require OAuth, SMS requires phone verification with a 10/day cap, and the feed is always on. It does not repeat annotation data and does not contradict it.

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

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

The description is dense and organized: it leads with purpose, then return, authentication, supported types, and delivery channels. It is about 100 words and every sentence adds value, though the dense prose is slightly run-on and could be better structured with bullets or line breaks.

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 major types and delivery channels but omits patent_grant and clinical_trial from its 'Supported types' list, even though they are in the schema enum. It also does not mention webhook delivery in the description, relying on the schema for that. Given the schema fills these gaps, it is not severely incomplete, but an agent reading only the description would have an incomplete 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 has 100% coverage with detailed descriptions for all parameters, including type-specific examples and delivery options. The description adds a bit of extra semantic meaning (e.g., items:['5.02'] = officer change), but most examples are duplicates of schema content. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description uses a specific verb 'Create' and clearly identifies the resource: 'a proactive monitoring subscription to a live-data event stream.' It also mentions the return of the subscription id, distinguishing it from listing, unsubscribing, or alert-fetching sibling tools.

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

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

It explicitly states the OAuth account requirement and points out that anonymous/BYO cannot persist, giving a clear precondition. It also mentions the feed is always on and can be pulled via recent_alerts or a direct GET, indicating an alternative for one-off retrieval. However, it does not explicitly name sibling tools like list_subscriptions or unsubscribe for comparison.

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 non-destructive, so safety is covered. The description adds valuable context about the return structure (category-bucketed example questions with tool + argument shape) and the live catalog source, beyond what annotations provide. 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 moderately long but well-structured, starting with user-like queries and then explaining the tool's function and usage. Each sentence adds useful information (output categories, parameter behavior, when to use). It is not excessively verbose for the scope of the tool.

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

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

For a tool with one optional parameter and no output schema, the description covers purpose, usage, parameter semantics, and output characteristics (categories, tool+argument shape). It also mentions related meta-tools, giving a complete onboarding picture. The only minor gap is not explicitly listing return types for the question objects, but the description sufficiently conveys 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?

The schema covers the single optional 'topic' parameter with a full description of values and behavior (omit for cross-category spread). The description adds only redundant examples like 'finance', 'pharma', 'betting', which do not significantly expand understanding. With 100% schema coverage, 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 identifies the tool as the onboarding entry point for suggesting example questions, with a specific verb ('returns category-bucketed example questions') and resource. It distinguishes itself from siblings by positioning as the first thing to use and mentioning meta-tools like ask_pipeworx, entity_profile, compare_entities.

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

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

The description explicitly states when to use this tool ('Use this FIRST when you do not yet know what Pipeworx can do for you') and provides guidance on alternatives by naming meta-tools to learn how to call. It also explains the parameter variation for focusing, giving clear context.

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

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

Annotations already indicate non-destructive and idempotent behavior, but the description adds valuable context: ownership is enforced, and the row is deactivated not deleted, preserving historical events via recent_alerts. 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 concise (two sentences), front-loaded with the action, and every sentence adds value (ownership, deactivation, historical availability). No wasted words.

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

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

Given the simple one-parameter tool, the description covers purpose, ownership, side effects, and relation to recent_alerts. With good annotations and no output schema, this is adequately complete.

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

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

Schema coverage is 100%, so the description does not need to repeat parameter details. The description adds minimal extra meaning beyond the schema (id is a uuid from subscribe), but it does not deeply enhance parameter understanding.

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

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

The description clearly states the tool cancels a subscription by id, using a specific verb and resource. It distinguishes itself from sibling tools like subscribe and list_subscriptions by clarifying the cancel action and its deactivation behavior.

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

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

The description provides clear context on when to use this tool: to cancel a subscription, with the ownership constraint (only your own). It also hints at an alternative for viewing history (recent_alerts), but it does not explicitly say when not to use this tool or name direct alternatives.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description reveals important behavior: the SEC/XBRL fast path, fallback to grounded pipeline, verdict enumeration, pipeworx:// citation inclusion, and the critical distinction between could_not_verify and unsupported. This is rich context 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 dense but well-organized, leading with examples and then covering routing, return values, and error semantics. It is longer than ideal, but every clause adds useful context; the structure could be slightly tightened but remains efficient 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 convey return behavior, and it does: verdict types, evidence with citation, reasoning, and the meaning of error-ish verdicts. Routing, source selection, and the 'replaces sequential calls' context make this 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?

Schema description coverage is 100% for both parameters, with detailed schema text for claim and tolerance_pct. The tool description itself does not add parameter-specific semantics beyond the schema, so the baseline of 3 applies.

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

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

The description opens with concrete query paraphrases and clearly states the tool's function: natural-language claim verification against authoritative sources. It distinguishes itself from generic ask/search tools by emphasizing verdict + citation output and the structured SEC EDGAR fast path, making its purpose unmistakable.

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

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

It explicitly says 'Use whenever the agent needs to check whether something a user said is factually correct' and clarifies the routing for company-financial vs. other claims. It also frames the tool as a replacement for 4–6 sequential calls, implicitly describing the alternative workflow it obviates.

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