Arcgis Lincolnne

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

Annotations declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: default model is free, Anthropic calls require a BYO key with direct billing to the user, and the response format includes per-model score, confidence, signals, raw_response, and combined view. It also reveals that _apiKey is passed straight through to api.anthropic.com, disclosing external network behavior beyond annotations.

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

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

Three sentences front-load the core purpose, then add usage context and technical details. Every sentence contributes unique information with no redundancy or fluff.

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

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

While there is no output schema, the description explicitly mentions the return structure (per-model score, confidence, signals, raw_response + combined view). It also covers usage scenarios and cost implications. It doesn't explain what 'signals' means or how the score is computed, but for a probe tool with good annotations, this is 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 coverage is 100%, so all parameters are well-documented. The description adds extra meaning by explaining the default model behavior (workers-ai default), that _apiKey is only needed if 'anthropic' is in models, and that context helps disambiguate common names. This goes beyond the schema's literal descriptions.

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

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

The description clearly states the tool probes LLMs for knowledge about a business/brand/product/topic and scores visibility (0-100) per model. It uses a specific verb (probe) and resource (LLMs), and distinguishes itself from siblings like ask_pipeworx by focusing on visibility scoring rather than answering questions.

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

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

The description provides clear usage contexts: AI-marketing audits, pre-launch brand checks, competitive monitoring. It also explains the default model and optional Anthropic probing. However, it doesn't explicitly mention when NOT to use this tool or compare it to alternatives like scan_competitor_ai_presence, so it loses a point.

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

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

Beyond the readOnlyHint/idempotentHint annotations, the description reveals material behavior: it routes questions to the right tool across thousands of sources, fills arguments, returns the result with citations, works on every tier, and even handles live news. There is no contradiction with the annotations.

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

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

The description is long but information-dense: every sentence provides a distinct piece of decision-relevant context, from top-level preference directives to trigger phrases, examples, sibling comparisons, and tier notes. It is front-loaded with the most important instruction.

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

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

Given there is no output schema, the description sufficiently explains return value style via 'structured answer with stable pipeworx:// citation URIs'. It also covers when to use this tool, when to step up to a sibling, and what types of questions are in scope, making the tool selection and invocation context complete.

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

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

The input schema is fully documented at 100% coverage, including all aliases for 'question'. The description adds natural-language examples, but the schema already carries the semantic burden. Since the description does not deepen parameter semantics beyond examples, the baseline 3 is appropriate.

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

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

The description clearly states the tool's function: it routes questions about factual, real-world data to 5,564 tools across 1,462 sources and returns structured answers with stable pipeworx:// citation URIs. It distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research by explicitly naming when those should be used instead.

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

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

The description provides explicit when-to-use guidance: prefer it over web search, use it for factual questions, always start here unless a hallucination-resistant grounded answer or broad deep research is needed. It gives concrete trigger phrases and examples, clearly differentiating it from sibling alternatives.

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

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

Annotations already declare read-only, open-world, idempotent, non-destructive. The description adds valuable context beyond annotations: it is an experimental edge with candidate routing improvements, currently inactive, so it matches ask_pipeworx exactly. It also clarifies that it is a full working router with no fallback. 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 composed of four sentences, each adding meaningful information: beta status, identical behavior, usage time, and experimental nature. It is slightly verbose but not wasteful, and the key points are front-loaded in the first sentence.

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

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

The tool is a complex router with 5,564 tools and no output schema. The description compensates by stating it has the same response shape as ask_pipeworx, conveying expected return format. It also explains the current state (no active candidate) and that it is a full working router. This is reasonably complete for an experimental variant.

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 description coverage, with all aliases documented. The description does not add extra parameter semantics, but the schema already fully explains the six parameters and their aliases. Baseline 3 is appropriate because the schema carries the heavy lifting.

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

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

The description clearly states it is a 'Beta version of ask_pipeworx' and a 'universal router' with the same 5,564 tools, same arguments, and same response shape. This distinguishes it from the sibling ask_pipeworx by its beta/experimental nature and explicitly mentions the routing improvements.

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

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

It provides explicit usage guidance: 'Use it exactly like ask_pipeworx when you want the newest routing.' It also explains that results are compared against the stable router to decide merges, giving context on when to choose this variant. It does not explicitly name alternatives, but the sibling list and the reference to ask_pipeworx imply the stable alternative.

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

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

Beyond the annotations (readOnly, openWorld, idempotent), the description discloses refusal behavior, exact refusal reasons, return structure including verbatim evidence and confidence, and the extra LLM call cost. It gives agents a precise model of success and failure outcomes.

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 earns its place: purpose, routing behavior, return structure, refusal reasons, use cases, and cost comparison. It is front-loaded with the core capability and then layers necessary detail without fluff.

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

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

Given no output schema, the description thoroughly explains return values, evidence, confidence, source, and refusal reason values. It also addresses the relationship to ask_pipeworx and the high-stakes context. The tool is complex, and the description covers the essential operational behavior completely.

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

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

Schema coverage is 100%, so the schema already documents all six parameters as natural-language question aliases. The description adds no new parameter syntax or format details beyond reinforcing that a natural-language question is accepted, so the high-coverage 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 a specific verb and resource: it is a 'hallucination-resistant answer mode' that extracts answers only from tool results. It explicitly distinguishes itself from the sibling ask_pipeworx by describing the additional extraction and refusal behavior.

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

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

Provides explicit when-to-use guidance: use when answers will be 'quoted, cited, or acted on' and the agent must not invent facts. It also explicitly says to prefer ask_pipeworx for casual lookups, making the alternative clear.

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

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

Annotations already declare readOnly/openWorld/idempotent/destructive flags. The description goes far beyond that by disclosing behavior: parallel fan-out to category-specific data packs, response shape fields, resolver contract with match confidence and alternatives, parent-event extraction, news fallback mechanisms, safety short-circuiting for low-confidence matches, closed/dead market handling, illiquidity flags, and cancellation-rule risk. This is highly transparent about what happens during execution and what edge cases an agent must watch for.

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: it front-loads purpose, then uses uppercase section labels (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK) to organize dense information. Every section contains actionable specifics—no filler. It could arguably be trimmed, but for a tool with this much behavioral complexity, the length is justified and the structure makes it scannable.

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

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

There is no output schema, so the description carries the full burden of explaining return values. It covers response shapes (market, analysis, evidence), resolver contract (match confidence, alternatives, suggestions), parent_event extractor, news field fallbacks, safety statuses, closed-market behavior, illiquidity flags, and cancellation-rule parsing. This is comprehensive enough for an agent to use the tool correctly and interpret results even without an output schema.

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

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

The input schema already covers all parameters with descriptions (100% coverage), including the market slug/URL/question formats, depth enum semantics, and include_raw behavior. The description adds some context (e.g., explicit market input examples and fan-out examples) but does not materially enhance parameter understanding beyond the schema. Since schema coverage is complete, a baseline 3 is appropriate.

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

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

The description opens with a specific verb+resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes itself from sibling tools like polymarket_edges or polymarket_arbitrage by framing its purpose as researching bets ("should I bet on X"). The use cases are explicitly stated with concrete examples and classifier categories, making the tool's scope unambiguous.

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

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

The description explicitly tells when to use this tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides detailed fan-out examples showing what kind of data each bet category fetches. However, it does not explicitly state when NOT to use it in favor of a specific sibling tool (e.g., polymarket_edges), so it lacks explicit exclusions/alternatives, though the stated use cases are clear enough.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), filtering logic (latest 10-K revenue, net income, cash, long-term debt; adverse-event counts), handling of off-calendar fiscal years, sorting by primary metric, and return format (paired data + citation URIs). 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 not wasteful; every clause adds value (trigger phrases, data sources, fiscal year handling, sorting, citations). It is front-loaded with usage patterns. However, it is a long single paragraph with semicolons and dashes that could be more scannable with bullet points or clearer sentence breaks, slightly reducing 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—two entity types, multiple data fields, sorting, citations, fiscal year nuances—the description covers all essential behavioral details. No output schema exists, so the description compensates by stating the return format (paired data + pipeworx:// citation URIs). It also provides efficiency context ('replaces 8–15 sequential lookups'), making the tool's value and place among siblings clear.

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%, providing baseline. The description enriches parameter meaning by explicitly mapping each 'type' value to its data source and metrics (company -> 10-K financials, drug -> FAERS/FDA/trial counts). It also clarifies 'values' format with examples ('AAPL','MSFT' for tickers; 'ozempic','mounjaro' for drugs) and the 2–5 item limit, going beyond the schema's terse descriptions.

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

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

The description clearly states it performs side-by-side comparison of 2–5 companies or drugs in a single parallel call, which distinguishes it from sibling tools like entity_profile and sequential lookups. Specific verbs ('compare', 'rank') and resource ('entities') make the purpose unambiguous. The mention of data sources and sorting further clarifies what the tool does.

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

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

Explicit trigger phrases are provided ('Compare X and Y', 'X vs Y', 'which is bigger', 'rank these companies', 'head to head'). It explicitly instructs 'ALWAYS PREFER over sequential single-pack lookups when comparing entities', giving a clear directive and alternative. Context about off-calendar fiscal years and sorting by primary metric tells the agent when and how results will be delivered.

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

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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, and the description goes well beyond by disclosing account requirements, paid tier for 'thorough', return format (findings packet with gaps[], contradictions[], hop, citation_uri), semantic excerpting of large records, and expected latency (15-60s, up to ~90s). This adds substantial behavioral context without contradicting the annotations.

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

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

The description is long but densely packed with distinct, high-value details. It is structured with clear separations (keywords, examples, caveats) and front-loaded with the critical account requirement. Slight redundancy ('this is NOT open-web search' could be inferred) keeps it from a 5, but every section earns its place for such a complex 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?

With no output schema, the description thoroughly explains the return packet: 'verbatim evidence + confidence + source + fetched_at + a stable pipeworx:// citation per finding', plus gaps[] and contradictions[]. It covers auth, alternatives, performance, and grounding behavior, making it fully complete for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for 'question' and 'depth', but the description enriches parameter meaning by explaining what 'depth' values trade off (quick=3 facets, standard=3 with gap recovery, thorough=6 with iterative chase), how they affect the contradiction scan, and the cost implication. It also reinforces that 'question' can be broad/multi-part, adding context beyond the schema.

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

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

The description clearly states the tool's function: 'Grounded multi-source research across Pipeworx's 1462 STRUCTURED data sources' and 'Decomposes your question into focused facets, routes each to the right one of 5,564 tools IN PARALLEL.' It also distinguishes from sibling tools by positioning itself for broad/multi-part questions versus ask_pipeworx for single lookups, making its unique value 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?

Usage guidance is explicit with alternatives: 'For a single lookup use ask_pipeworx', 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx', and 'If you are not signed in, use ask_pipeworx instead'. It also clarifies depth-dependent behavior (standard re-angles gaps, thorough chases leads) and time expectations, giving the agent clear decision criteria.

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

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

Annotations already cover readOnly, idempotent, and non-destructive traits. The description adds valuable behavioral context: returns top-N tools with full schemas and curated examples, ready to call directly without a second schema lookup. This goes beyond the structured annotations and informs the agent of the tool's practical output.

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

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

The description is three sentences, front-loaded with the core function. The domain list is long but valuable for an agent to know coverage. The return-value explanation is concise and every sentence earns its place.

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

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

Although no output schema exists, the description fully explains the return format (top-N tools with names, descriptions, full schemas, examples). With 6 simple parameters and strong annotations, the description covers purpose, usage, and behavior comprehensively.

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

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

Schema coverage is 100%, with all aliases (query, task, q, description, search) and limit documented. The description adds no further parameter meaning beyond schema examples already present; it merely reiterates the alias acceptance. 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 uses a specific verb+resource construction: 'Find tools by describing the data or task.' It clearly distinguishes itself from sibling search tools by positioning as a meta-discovery tool ('Call this FIRST when you have many tools available'), which is explicit differentiation.

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

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

It states when to use: 'Use when you need to browse, search, look up, or discover what tools exist' and recommends calling first. It also implies when not to use ('not just one answer'), but does not explicitly name alternatives or provide exclusion conditions, so it misses the top tier.

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

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

Despite strong annotations, the description discloses rich behavioral details: parallel fan-out across multiple sources, soft-fail behavior for patents due to USPTO API sunset, GDELT→GNews fallback for news, and specifics about output formats (e.g., pipeworx URIs, sorted fundamentals). This goes well beyond the annotation hints and informs the agent about non-obvious failure modes and data provenance.

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

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

The description is long but densely structured, leading with user-intent examples then capturing purpose, usage, output components, and constraints in a single block. While some repetition of schema details exists, the length is justified given the tool's complexity and the absence of an output schema, though it could be tightened by trimming repeated examples.

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 supplies a complete return structure (cik, company_name, recent_filings, fundamentals, patents, news, LEI), including limits and source links. It also covers input constraints, fallback behavior, and known limitations (e.g., name not supported), providing enough context for an agent to invoke the tool correctly without ambiguity.

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

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

The input schema already covers both parameters in full, including examples ('AAPL', '0000320193') and the name limitation. The description merely repeats this information without adding new semantic meaning, so it meets the baseline for 100% schema coverage but does not exceed it.

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

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

The description clearly states the tool creates a 'full cross-source profile of a US public company' in one parallel call, with specific verbs like 'fans out' and 'returns'. It distinguishes from siblings by explicitly noting to 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups' and referencing resolve_entity for name-based lookups, making the tool's scope unambiguous.

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

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

It provides explicit when-to-use guidance ('when the user asks for a holistic view') and an exclusion for name inputs, directing users to 'use resolve_entity first'. This clearly differentiates it from alternative tools and gives actionable decision criteria.

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 and idempotentHint, so the description only adds slight purpose context (e.g., clearing sensitive data) without new behavioral details like error handling or permanence.

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, front-loaded sentences with no filler; every sentence contributes to purpose or usage.

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

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

For a simple one-parameter memory deletion tool with robust annotations (destructive, idempotent) and no output schema, the description provides sufficient usage context to be effectively complete.

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

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

Schema coverage is 100% with a clear parameter description ('Memory key to delete'); the description's 'by key' reinforces this but does not add extra semantic detail 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 uses a specific verb and resource ('Delete a previously stored memory by key') and clearly distinguishes the tool from sibling memory tools like 'remember' and 'recall'.

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 contexts ('context is stale, task is done, sensitive data') and mentions pairing with 'remember' and 'recall', but does not explicitly state exclusions or 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, idempotentHint, and destructiveHint. The description adds behavioral context by noting it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which goes beyond annotations and clarifies the operation's process. 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 compact (3 sentences), front-loaded with the main purpose, then process, then use cases. Every sentence provides unique value with no redundancy or fluff.

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

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

Despite lacking an output schema, the description fully explains the return value ('single text blob ready to drop at site-root/llms.txt') and the tool's behavior. The annotations and schema cover safety and parameters, making the description complete for a simple generation 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 provides full descriptions for both parameters (url and max_links) with 100% coverage. The description adds general context about extraction ('key links') but does not add specific parameter-level meaning beyond the schema. Baseline 3 is appropriate given complete 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 uses a specific verb+resource: 'Generate a production-ready llms.txt file for any URL'. It clearly differentiates from sibling tools by focusing on producing the actual llms.txt file, including its format and placement, rather than just checking AI visibility or scanning 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 three use cases ('getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor'). This provides clear context for when to use the tool, though it does not enumerate when-not-to-use or alternatives among sibling tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying exactly what result contents the agent can expect (fields, geometry type, record count, capabilities) since there is no output schema. It does not mention network/auth/rate-limit details, but the annotations lower the burden and the added output detail is useful.

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

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

The description is a single sentence, front-loaded with the verb 'Get', and includes a comma-separated list of return items. It is concise, scannable, and free of filler.

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

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

For a simple one-parameter read-only tool, the description is complete: it states the purpose, the input (url), and lists the output contents despite no output schema. Annotations provide full safety context, and no further detail is necessary.

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 single parameter 'url' is fully described with an example. The description says 'by url' which adds no meaningful semantics beyond the schema. The baseline of 3 applies since the structured schema already documents the parameter.

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

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

The description uses a specific verb 'Get' and identifies the exact resource (ArcGIS Feature/Map Service layer's schema) with a clear list of returned data: fields, geometry type, record count, and capabilities. This fully distinguishes it from sibling tools like query_layer, which presumably retrieves feature data rather than schema metadata.

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

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

The description implies usage clearly: use this tool when you need layer schema/metadata rather than querying features. However, it does not explicitly name alternatives or state when not to use it, so it misses the highest bar but provides adequate 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 declare readOnly and non-destructive behavior. The description adds context by specifying the return fields and that subscriptions are scoped to the caller, and that only active ones are listed by default. This 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?

Two sentences, front-loaded with purpose, then return fields, then usage guidance. No wasted words, 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?

Simple tool with one optional parameter and no output schema. The description provides the purpose, return fields, and usage guidance, which is complete for a list tool. It doesn't mention include_inactive, but the schema covers that.

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 parameter description in the schema is sufficient. The tool description does not add any additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.

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

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

The description clearly states the tool lists the caller's active subscriptions, with a specific verb and resource. It also lists the returned fields, distinguishing it from sibling tools like subscribe and unsubscribe.

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

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

Provides explicit use cases: review what you're monitoring before adding more, or find an id to cancel. Implies alternatives (subscribe/unsubscribe) without naming them, so it's clear but not exhaustive.

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 no hints (all false), so the description carries the full burden. It discloses the claim_token return flow ('Filing without an account returns a claim_token'), human review cadence ('team reads digests daily'), rate limits ('5 per identifier per day'), and cost ('doesn't count against your tool-call quota'). 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?

Long but every sentence earns its place: purpose, trigger conditions, exclusions, token flow, review expectations, limits, and cost. Information is front-loaded – the first two sentences state purpose and usage, with details following logically.

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 4-param optional-args tool with no output schema, the description is remarkably complete: it covers when to use, what to include, what response to expect (claim_token), follow-up mechanics, and operational constraints. The absence of an output schema is mitigated by describing token retrieval and review outcomes.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value by explaining claim_token's two-phase usage ('pass it back later as pipeworx_feedback(...)'), advising 'describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt,' and noting rate-limit implications. These add meaning beyond the schema 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?

Description opens with a specific verb+resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It clearly distinguishes itself from siblings by scoping to 'tools served by this Pipeworx connection' and explicitly contrasts with other MCP servers.

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 lists when to use (bug, feature/data_gap, praise) and provides a clear exclusion: if the tool came from a different MCP server, 'file it with that server instead.' Also adds disambiguation: 'Not sure? Pipeworx tool names are the ones this connection lists.'

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

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

Annotations already declare readOnly, idempotent, openWorld, non-destructive. The description adds non-obvious behavioral details: caching window (5min-1h), derivation from CF analytics-engine, no PII, and the data shape (pack, tool, count). This enriches beyond annotations.

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

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

Four sentences, front-loaded with the core function, followed by use cases and technical notes. No waste; each sentence adds value.

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

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

Given one optional parameter, strong annotations, and full schema coverage, the description sufficiently covers purpose, interpretation, caching, and data shape. It lacks an output schema but the described return content is adequate for agent use.

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 single parameter `window` has 100% schema description coverage with enum and semantics explaining short vs long windows. The tool description reiterates the 24h/7d/30d options but does not add new syntax; baseline of 3 applies.

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

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

The description opens with a clear question framing ('What other AI agents are calling on Pipeworx right now') and explicitly states it returns top tools, top packs, and total call volume. It distinguishes this from sibling tools by focusing on aggregated peer usage signals.

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 'Useful for' section lists three concrete scenarios (hot data sources, confirming canonical tool, aligning use case), giving clear context for when to call this tool. It does not explicitly name alternative tools, but the scenarios imply when it is appropriate versus when to use search or discovery tools.

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

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

The description goes far beyond the provided annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing the fill check against CLOB depth, realizable edge threshold, placeholder filtering behavior, and the Jaccard similarity anchor. It also warns 'do not trade it' when realizable_edge_pp <= 0, adding critical 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 long, but well-structured with clear section headers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose and mode selection. Every sentence provides value; a slight trim could improve scannability without losing 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?

Given no output schema, the description fully specifies the response structure for both modes, including field names and the fill-check logic. It also covers edge cases like placeholder filtering and low similarity, making it effectively complete for a complex, multi-mode 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?

Although the schema already covers both parameters with descriptions and examples, the tool description adds deep semantic meaning: it explains how event and topic modes behave, what happens with each input, and how they differ. This goes well beyond the schema's basic descriptions.

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

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

The description clearly states the tool finds arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks, and explicitly distinguishes three usage modes (no args, event, topic). It also differentiates itself from the sibling polymarket_fill_risk by pointing to it for custom sizing.

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

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

Provides explicit when-to-use guidance: no args for a trending scan, event for a specific market, and topic for cross-event scanning. It also explains trade-offs (cross-event catches single-event misses) and points to polymarket_fill_risk for custom sizing, giving clear alternatives.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses substantial behavioral details: the three response segments, per-opportunity fields (edge_pp_net, kelly_fraction, liquidity), the 24h-move warning, the caching behavior ('Cached 1h at the KV level'), and diagnostic counters. It even explains why Fed signals are excluded and why partition arbs report kelly_fraction_half=0 at parent level.

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, with substantial jargon and nested details. It is front-loaded with the core purpose, but the sheer volume of information (model-family specs, partition math, caching, diagnostics) makes it less concise than ideal. Every sentence carries some value, but the overall size exceeds what is needed for an agent to select and invoke 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?

With no output schema provided, the description compensates by fully outlining the response top-level structure (by_segment, fed_candidates, _diagnostics), the meaning of empty segments, and the effect of knobs. It also covers edge cases like the placeholder-slug filter and Fed-signal unreliability, making it complete for an agent to understand what to expect and how to adjust inputs.

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

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

The input schema already provides 100% coverage with thorough descriptions for every parameter (e.g., min_liquidity explains 'Minimum $ liquidity... Set to 5000 to drop thin-book opportunities'). The description adds a conceptual grouping ('TRADEABLE-EDGE KNOBS') and mentions three parameters, but this does not materially exceed the schema's own documentation.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also states the intended use case ('what should I bet on today'), and the detailed model-family breakdown clearly distinguishes this from sibling tools like polymarket_arbitrage or polymarket_fill_risk.

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 a clear context for when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It does not explicitly mention alternatives or when not to use it, but the use case is sufficiently specific.

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

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

While annotations already mark the tool as read-only and idempotent, the description adds substantial behavioral detail: it discloses the snapshot-based data source, TTL limits, cache-miss gaps, and that decay numbers come from daily closes rather than intraday. It also explains the meaning of expired vs. tracked opportunities, going 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 long but well-structured, beginning with the core purpose, followed by args, response format, and limits. It uses bolded response keys for clarity and every section contributes to understanding the tool's behavior. While verbose, the complexity of the tool and the lack of an output schema justify the 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?

With no output schema, the description fully documents the return structure: tracked[] with its subfields (trend, decay_pp_per_day, first_seen), expired[] with lifespan_days, and snapshot_dates[] with explanations of data gaps. It also covers data freshness limits (TTL) and the meaning of missing snapshots, making it highly complete for the tool's complexity.

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

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

The input schema already provides 100% coverage for both parameters, including defaults and ranges. The description restates these values ('days (lookback, default 14, max 30), window (snapshot family, default 1wk)') but does not add additional meaning or constraints beyond what the schema already specifies. This meets the baseline of 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 provides 'edge persistence and decay telemetry' and answers the specific question 'how long has this edge existed and is it shrinking?'. It distinguishes itself from merely listing current edges by contrasting fresh vs. old edges, which differentiates it from the sibling polymarket_edges tool.

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

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

The description gives clear context on when to use the tool by framing the trade-significance of edge age, implying it's for historical decay analysis rather than current edge values. However, it does not explicitly name alternative tools or state when not to use this one, 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 declare readOnlyHint/idempotentHint true, but the description adds significant behavioral context: it walks the ladder, returns verdicts (clean|degraded|cannot_fill), and discloses the risk of partial basket fills converting arbs into unhedged directional positions. It also explains mode-dependent size_usd interpretation. 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 structured with REQUIRES/SINGLE-MARKET/BASKET sections and a closing USE THIS rule. It is front-loaded with the core purpose. While dense, every section contributes necessary details for two distinct modes; no fluff is present, though a bit more whitespace could improve scannability.

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

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

There is no output schema, so the description compensates by enumerating all return fields for both modes, including edge-case outputs like thin_legs[] and forced_directional_risk. It includes prerequisites (market or event required), default values, and the tool's safety implications. This is fully adequate for correct invocation.

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

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

Even though the schema covers all 4 params (100%), the description adds mode-dependent semantics not apparent from the schema: in single-market, size_usd is 'max spend on buys, target proceeds on sells', while in basket mode it's 'settlement notional S (shares per leg; each share pays $1)' with auto side selection from partition sum. This adds meaning beyond the schema fields.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes this tool from siblings by framing it as a pre-trade risk check for polymarket_arbitrage and polymarket_edges, not an execution or edge-discovery tool.

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

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

Explicitly states when to use: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500' and explains why (theoretical overround on thin books is not capturable; partial basket fills convert arb into an unhedged directional position). It also differentiates single-market vs basket modes with REQUIRES/SINGLE-MARKET/BASKET structure.

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

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

Annotations already declare read-only, idempotent, and non-destructive, so the description's burden is lower, but it still adds substantial behavioral context: compatibility_warning edge cases (non-equivalent bet shapes vs semantically unrelated topics), temporal alignment semantics, and skipped_cross_type/subtype counters. It also honestly warns that pre-mapped topics often return warnings and are not tradeable. No contradiction with annotations.

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

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

The description is long but well-structured with clear section labels (TWO MODES, RESPONSE, SAFETY FIELDS) and front-loads the core purpose. It could be trimmed slightly, but each sentence contributes necessary detail about edge cases and response semantics, so 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?

With no output schema, the description carries full responsibility for return-value semantics. It explains leg-by-leg prices, spread top_spreads_pp, compatibility_warning triggers, temporal_alignment fields, and skipped_cross_type/subtype counters. For a tool with 3 optional parameters and complex cross-venue matching logic, this is complete enough for an agent to use correctly.

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

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

Schema description coverage is 100%, and the description adds meaning beyond the schema: it explains the two modes, how explicit ticker/slug override the topic mapping, the list of topic shortcuts, and how the sign of top_spreads_pp is interpreted. This goes well beyond the schema's simple property descriptions.

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

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

The opening line 'Cross-venue spread between Kalshi and Polymarket for the same resolving question' clearly specifies the verb (compute/compare), the resource (cross-venue spread), and the scope (same resolving question). It distinguishes this from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison of the same outcome rather than intra-venue arbitrage.

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?

Describes two explicit usage modes: topic shortcuts and explicit ticker/slug pairings, with the topic list enumerated. It also gives strong caveats about when spreads are not meaningful via compatibility_warning and temporal_alignment. However, it does not name alternative sibling tools for comparison, so it lacks explicit when-not-to-use guidance relative to other tools.

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

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

Annotations already declare readOnlyHint=true, idleHint=true, and destructiveHint=false, establishing this is a safe read operation. The description adds value beyond annotations by stating it 'Returns attribute rows (and geometry)' and demonstrating a sampling pattern. It does not cover error handling or rate limits, but the annotations reduce the burden, and the added detail is useful.

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

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

The description is three sentences, front-loaded with the purpose, followed by parameter summary, and ends with return type and a usage tip. Every sentence contributes meaning without redundancy, making it concise and well-structured.

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

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

The description provides a complete picture for a query tool: it states the input (URL), the parameter types, the return content (rows and geometry), and includes a practical example for sampling. Given the rich schema and annotations, it does not need to explain return values in detail. Minor gaps like error handling and explicit comparison to layer_info are not covered, but overall it is sufficient for correct invocation.

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

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

Schema coverage is 100% with each parameter already described. The description briefly mentions 'SQL-like where', 'comma-separated out_fields', 'order_by', 'limit', 'offset', but this largely restates schema information. The sampling tip adds marginal value. Since the schema does the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Query an ArcGIS Feature Service / Map Service layer by its url'. This specifies the verb (query), the resource (layer), and the input (url). It also distinguishes itself from sibling tools like search_datasets (which finds datasets) and layer_info (which provides metadata) by focusing on querying a layer's data.

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

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

The description gives clear context by indicating the URL comes 'from search_datasets', implying a workflow where search_datasets is used first. It also provides a practical tip for sampling ('Use where="1=1" + out_fields="*" to sample'). However, it does not explicitly name alternatives or state when not to use this tool, such as when layer_info would be more appropriate.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable context beyond these: scoping to anonymous IP, BYO key hash, or account ID, and the behavior of listing all keys when no key is provided. This goes beyond the safety annotations and gives the agent a fuller mental model of the tool's behavior.

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

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

The description is three sentences: the first states the function, the second gives usage context with concrete examples, and the third covers scoping and related tools. There is no redundant fluff, each sentence earns its place, and the most important information is front-loaded.

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

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

Given the tool is simple (one optional parameter, no output schema) and the annotations already cover safety, the description fully covers the tool's purpose, usage, scope, and relationship to sibling tools. It does not need to describe return values because the basic function is obvious and no output schema exists to contradict.

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

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

Schema coverage is 100% and the schema already describes 'Memory key to retrieve (omit to list all keys)'. The description repeats this same information ('omit the key argument') without adding any substantial new dimension to the parameter's meaning. It adds the fact that values were 'previously saved via remember', but this is minor and 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 opens with a specific verb ('Retrieve') and clearly states two forms: retrieving a value by key or listing all keys by omitting the key. It explicitly references 'remember' and 'forget' as sibling tools, distinguishing itself from them. This is unambiguous and does not rely on the title.

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 says 'Use to look up context the agent stored earlier' and provides concrete examples (user's target ticker, address, prior research notes). It explicitly contrasts with re-deriving context from scratch and instructs pairing with 'remember' to save and 'forget' to delete. This gives clear when-to-use and alternative guidance.

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

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

The description states that setting mark_read:true flags returned events as read, causing future calls to only show newer events. This contradicts the annotations readOnlyHint: true and idempotentHint: true, which imply no state modification and idempotent behavior. The description reveals a side-effect, creating an annotation contradiction.

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

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

The description is four sentences, front-loaded with the main purpose. It includes necessary details about parameters and the alternative endpoint without excessive verbosity. Every sentence contributes useful 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?

Without an output schema, the description explains that each event carries source, citation_uri, and raw payload, covering the return format. It also addresses polling and provides an alternative access path, making the description fairly complete for a read-oriented 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 adds value by explaining the mark_read behavior (affects future calls) and providing a concrete type example ('sec_8k'), going beyond the schema descriptions.

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

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

The description clearly states the tool pulls fired events from the user's subscription feed, with a specific verb and resource. It distinguishes from siblings like recent_changes and list_subscriptions by focusing on alerts from the evaluator.

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

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

The description explains when to use the tool (poll for recent alerts), suggests filtering by type and since, and mentions that the same feed is available via an HTTP endpoint for scripts/dashboards, providing an alternative. It lacks explicit comparisons to sibling tools but offers clear usage 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 readOnly and idempotent hints, so the description adds substantial extra behavioral context: fan-out to multiple APIs, fallback chain (GDELT preferred, GNews on rate-limit/5xx), USPTO's soft-fail due to PatentsView sunset, and the return structure with pipeworx:// citation URIs. No annotation contradiction exists.

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

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

The description is dense but well-organized: example queries lead, then sources, parameter formats, return shape, and alternative tool. Every clause carries meaning, but it is slightly long; a bit of tightening could improve scannability without sacrificing detail.

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

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

For a complex multi-source tool with no output schema, this description is fully complete. It covers all data sources, fallback behavior, parameter syntax, return structure, and explicitly differentiates from a sibling tool. The readOnly annotation plus detailed description give the agent everything needed to invoke it correctly.

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

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

The input schema already documents all three parameters with 100% coverage, so the baseline is 3. The description reinforces since formats with examples and adds a usage tip ('30d or 1m for typical monitoring'), but this is marginal beyond schema content.

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' with natural-language example queries, enumerates the specific data sources (SEC EDGAR, GDELT/GNews, USPTO), and describes the returned changes[] structure. It also explicitly contrasts with entity_profile, distinguishing the time-windowed feed from a static profile.

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

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

It gives concrete usage contexts (e.g., 'what happened to Z this week'), notes the parallel execution benefit, and explicitly recommends entity_profile when a static profile is needed, including the fields that profile covers. The GDELT-to-GNews fallback behavior is also explained, helping the agent decide when this tool is appropriate.

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

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

Annotations already state idempotentHint=true and destructiveHint=false. The description adds valuable behavioral context: persistent vs. 24-hour memory ('Authenticated users get persistent memory; anonymous sessions retain memory for 24 hours') and scoping 'by your identifier.' This goes beyond structured fields without contradicting them.

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

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

Three sentences, each earning its place: purpose, when-to-use, storage/auth details, and companion tools. No fluff or repetition of annotation data. 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?

For a simple two-parameter write tool with no output schema, the description covers purpose, usage triggers, persistence semantics, and related tools. No critical context is missing; the agent can select and invoke this tool confidently.

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

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

Schema coverage is 100% with clear descriptions for both 'key' and 'value'. The description's mention of 'key-value pair' and examples like 'resolved ticker, target address' reinforces the schema but adds no new parameter-level meaning. 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?

Description opens with 'Save data the agent will need to reuse later' – a specific verb and resource. It distinguishes from siblings by explicitly naming 'recall' and 'forget' as complementary tools, making its role unique.

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

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

Provides explicit when-to-use guidance: 'Use when you discover something worth carrying forward' with concrete examples (resolved ticker, target address). Also names alternatives via 'Pair with recall to retrieve later, forget to delete,' clarifying when not to use this tool.

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

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

The description adds significant behavioral context beyond the annotations (readOnlyHint, idempotentHint, etc.). It details graceful degradation (LEI/FIGI enrichment falling back to EDGAR), cascading internal lookups, labelled identifiers from sources, and explicit reporting of unresolved identifiers. 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 well-structured, starting with usage examples and then explaining supported types. It is relatively long but every sentence provides valuable detail. Minor reduction in length could improve conciseness, but it remains efficient for the complexity covered.

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

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

Given the tool's complexity (two entity types, multiple identifier sources, fallback behavior) and the absence of an output schema, the description is remarkably complete. It covers input variations, resolution behavior, graceful degradation, and what the output includes (labelled identifiers, unresolved list). No gaps remain.

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

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

The schema already has 100% coverage with descriptions for both 'type' and 'value'. The description enriches this by explaining the specific input formats (e.g., ticker, CIK, ISIN for company; brand or generic name for drug) and adding context like ISIN-to-LEI mapping. This adds meaning beyond the schema's basic definitions.

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: resolving user-spoken names to canonical/official identifiers. It provides specific examples ('ticker for...', 'find the CIK for...') and lists supported entity types (company, drug) with detailed explanations. This distinguishes it from sibling tools, which cover other domains like search, research, or alerts.

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 advises 'Use FIRST whenever you have a name but need an ID,' giving clear guidance on when to invoke the tool. It also notes that the tool replaces 2-3 manual lookups, implying efficiency. However, it does not provide explicit when-not-to-use scenarios or directly compare to alternatives among the sibling tools.

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

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

Annotations already declare the tool read-only, idempotent, open-world, and non-destructive. The description adds process-level transparency by stating it probes each entity with ai_visibility_check and returns a ranked list with score, confidence, and signal density. It does not contradict 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 tightly written sentences: first states the core purpose, second explains the process, third gives a use case and output summary. No fluff or repetition.

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

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

The description, combined with full schema coverage and annotations, gives a complete picture. It covers what the tool does, how it works (calls ai_visibility_check), and what it returns (ranked list with score, confidence, signal density). Even without an output schema, the description fulfills that need.

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 all parameters are already documented. The description adds minimal extra meaning (e.g., 'entities' as brand+competitors) but does not provide syntax, format, or usage details beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from the sibling ai_visibility_check by explaining it probes each entity with that sub-tool and ranks results, making it a comparative aggregate tool.

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

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

The description gives a specific, actionable use case ('competitive AI-marketing audits') with an example question. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a perfect score.

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

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

Beyond the readOnly/idempotent annotations, the description discloses partial failure behavior ('Partial failures degrade gracefully'), latency expectations ('bundlephobia's first measurement... can take 5-30s'), and output structure ('Returns a summary block... per-advisory detail, links, and a list of recent alternative versions'). This adds significant 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 well-organized: purpose, usage triggers, ecosystem limits, failure modes, and return summary in a compact paragraph. Every sentence contributes operational value with no redundancy or filler.

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

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

Given the tool's complexity (multiple data sources, composite output) and missing output schema, the description comprehensively covers the summary block fields, per-advisory details, and graceful degradation. It also sets expectations for federation across two external APIs, making the tool's behavior predictable.

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% — both 'package' and 'version' are already described. The description adds no parameter-specific usage details; it only mentions npm ecosystem scope, which the schema already conveys. Baseline 3 is appropriate.

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

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

The description opens with a clear verb and resource: a composite 'should I add this npm package to my project' check, listing the exact data sources (deps.dev + bundlephobia) and scope (npm). It differentiates from siblings like scan_competitor_ai_presence by focusing specifically on dependency safety, size, and version history.

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

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

It explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also provides exclusions and alternatives: 'NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly.'

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context about 'open' geospatial datasets, the return structure (name, summary, record_count, owner/org, URL), and the chaining behavior. No contradiction.

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

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

Two tightly packed sentences: the first states the action and resource, the second lists return values and next steps. No filler or redundant repetition of schema 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?

Despite lacking an output schema, the description fully explains return fields and how to use them. It also gives enough context about the data scope and the discovery-to-query workflow, making it self-sufficient for an agent to decide and proceed.

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

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

Schema coverage is 100% with descriptive parameter text. The description adds little beyond the schema: it mentions 'by keyword' (mapping to query) and return fields, but doesn't elaborate on limit or org_id behavior beyond what the schema already states.

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 ('Search') with a clear resource ('Lincoln & Lancaster County GIS open geospatial datasets') and scope (by keyword). It also distinguishes itself from siblings like query_layer and layer_info by explicitly stating it returns Feature Service URLs for those tools to consume.

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

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

The description gives clear context: use this to discover datasets and then pass the returned URL to query_layer/layer_info. This implies a workflow and names alternatives. However, it does not explicitly contrast with other search-like siblings (e.g., search_within), so it lacks a 'when not to use' statement.

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, destructiveHint. The description adds substantial behavioral context beyond annotations: truncation at 200K chars with a flag, overlapping 500-char windows, embeddings model, cosine similarity, and output includes offsets/scores. No contradiction.

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

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

The description is a bit lengthy but every sentence contributes: purpose, use case, mechanics, limits, and pairing with a sibling. The main verb and resource are front-loaded. Slight redundancy in the second sentence about 'saves context' and 'returns only the passages that matter' but not excessive.

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 explicitly describes the return value: 'top-N passages with character offsets and similarity scores.' It also covers edge cases (truncation, length cap) and the algorithm used. For a 3-parameter tool with no output schema, this is fully complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value by clarifying the 'text' parameter with concrete examples (SEC 10-K body, article) and providing example queries for 'query'. It also explains the cap of 200K chars, which the schema mentions in parentheses but the description enriches with the truncation flag behavior.

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

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

The description opens with a specific verb+resource: 'Semantic search INSIDE a fetched record.' It clearly distinguishes from siblings by emphasizing the input is text the agent already pulled, not a corpus-level query. Examples (SEC 10-K, article) reinforce the scope, making it hard to confuse with ask_pipeworx 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?

Explicitly states when to use: 'Use when the record is too big to cram into the prompt.' It also names an alternative workflow: 'Pairs with ask_pipeworx_grounded: fetch with the gateway, ground over the relevant passages instead of the whole document.' This gives concrete context and differentiation.

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

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

The description goes far beyond annotations by disclosing auth requirements (anonymous/BYO cannot persist), delivery channel behaviors (feed always on, phone verification, 10/day SMS cap), and webhook specifics (HMAC signing, secret returned once, auto-disable after failures). These are valuable behavioral insights not present in the annotations.

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

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

The description is front-loaded with the core purpose and efficiently packed with all critical details in a well-structured format. Though dense, every sentence contributes necessary information about types, parameters, and delivery channels, making it appropriately sized for the tool's complexity.

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

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

The description is exceptionally complete for a tool with nested objects, multiple subscription types, delivery options, and no output schema. It covers authorization, type-specific parameters, delivery channel behaviors, and how to retrieve fired events, leaving no obvious gaps for an agent to use the tool correctly.

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

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

Despite 100% schema coverage, the description adds substantial parameter semantics with concrete examples for each type (e.g., items:['5.02'], topic:'fed', series_id:'UNRATE') and explains the delivery object's constraints (verified phone, signing secret). This goes beyond what the schema descriptions provide.

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

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

The description clearly states the tool's purpose with a specific verb ('Create') and resource ('proactive monitoring subscription'), and returns the new subscription id. It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on the creation aspect and enumerating supported subscription types.

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

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

The description provides clear context on when to use the tool (for monitoring live-data event streams) and includes prerequisites (OAuth account required). However, it does not explicitly mention alternatives or exclusions, such as 'use this instead of recent_alerts for one-time checks', leaving some implicit guidance.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable context about the return value (category-bucketed examples with tool shapes), the source (live catalog), and the effect of topic scoping. 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 longer than average but front-loaded with example user queries and ends with direct usage instructions. Each section adds necessary context, though the long list of categories could be trimmed slightly without losing value.

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

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

For a tool with 0 required params and no output schema, the description fully covers what it returns, how to invoke it, and when to use it. It leaves no gaps for the agent's decision-making.

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

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

Schema coverage is 100% with a description for the optional topic parameter. The description goes beyond by providing concrete example values ('finance', 'pharma', 'betting') and mapping topic to the category buckets listed. This helps the agent understand valid usage.

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+resource: 'onboarding entry point' and 'Returns category-bucketed example questions... with the exact tool + argument shape that answers it.' This clearly states what the tool does and distinguishes it from siblings like discover_tools by focusing on suggestions and getting started.

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

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

Explicit guidance is provided: 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools.' It also explains when to omit or pass the topic parameter. This gives clear when-to-use context even if it doesn't mention sibling alternatives by name.

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

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

The description adds significant behavioral context beyond the annotations: ownership enforcement (only your own subscriptions can be canceled) and the deactivation semantics (row is deactivated, not deleted, preserving historical events in recent_alerts). This goes beyond the structured readOnly/destructive hints and gives the agent actionable knowledge about side effects.

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

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

The description is only two sentences, front-loaded with the core action, then immediately provides the two key behavioral constraints (ownership and deactivation). Every word contributes value; there is no padding or redundancy.

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

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

For a simple single-param tool with no output schema and given the rich annotations (destructiveHint false, idempotentHint true), the description covers all essential aspects: what it does, who can use it, and what happens to the data. There are no notable gaps in context.

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

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

With 100% schema description coverage, the single 'id' parameter is already fully documented ('Subscription id (uuid) returned by subscribe'). The description's 'by id' adds no new semantic detail beyond the schema. The high schema coverage sets a baseline of 3, and the description does not compensate further.

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 ('Cancel') and resource ('a subscription') with a clear identifier ('by id'), making the tool's purpose unmistakable. It also distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions' by focusing on the cancellation action.

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

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

The description implies when to use the tool (to cancel a subscription) and provides important context about ownership and deactivation, but it does not explicitly name alternatives or state when not to use it. No direct contrast with other tools is given, so guidance is implied rather than explicit.

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 significantly extends the annotations by detailing the automatic routing between the SEC EDGAR + XBRL fast path and the grounded pipeline. It also explains the six verdict types, with a critical warning that could_not_verify means the check did not happen and must not be treated as evidence, and distinguishes unsupported as having no source coverage. This is valuable behavioral context beyond the readOnly/openWorld 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?

Although the description is long, it is dense with essential information: user intent examples, routing logic, verdict definitions, caller warnings, and an efficiency claim. The content is front-loaded with natural-language patterns and organized with an IMPORTANT callout, so every sentence earns its place.

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

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

Despite lacking an output schema, the description fully specifies the return payload (verdict, grounded/structured value with pipeworx:// citation, reasoning) and the failure modes (could_not_verify with verification_error vs unsupported). It covers scope, routing, and caller implications, leaving no significant gaps for a claim-verification 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 the schema descriptions for both parameters are fully self-explanatory, including tolerance_pct's range, default, and use cases. The tool description adds no extra parameter-specific guidance; mentioning 'exact percent-delta math' in the routing context is not unique parameter semantics.

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

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

The description clearly defines the tool as 'natural-language claim verification against authoritative sources' with specific user-phrasing examples. It distinguishes itself from sibling tools by explaining the two routing paths (SEC XBRL vs grounded pipeline) and the verdict output, making its unique role obvious.

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

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

The description explicitly states 'Use whenever the agent needs to check whether something a user said is factually correct.' It also clarifies the automatic fallback for non-financial claims and claims it replaces 4–6 sequential calls. However, it doesn't explicitly name alternative tools for non-fact-check use cases, so the when-not-to-use guidance is implicit rather than explicit.

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