Data Edmonton

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 meaningful context: the default model is free (Workers AI Llama-3.3-70b), probing Anthropic requires a BYO API key and direct payment to Anthropic, and the return format is per-model with specific fields. 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 only two sentences, front-loaded with the core action and output, followed by a concrete example. Every phrase earns its place, including the return format and use cases. No wasted words.

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

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

With no output schema, the description compensates by outlining the return structure (per-model fields plus combined view). It covers key aspects: default model, optional Anthropic key, and use cases. It could elaborate on what 'signals' are, but overall the tool is well-contextualized for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds extra semantics: it identifies the default model, clarifies that _apiKey is only needed for the 'anthropic' model, and notes the cost implication (paid directly to Anthropic). This goes beyond the schema's field 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 action (probe LLMs) and the resource (business/brand/product/topic), and specifies the output (visibility score 0-100). It distinguishes itself from siblings like ask_pipeworx and deep_research by focusing on AI visibility measurement across models.

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 concrete use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) indicating when to use the tool. It does not explicitly mention alternatives or exclusions, but the context is clear enough for selection 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?

While annotations already declare readOnly/openWorld/idempotent, the description adds useful behavioral context: routes to 5,529 tools, fills arguments automatically, returns structured answers with stable pipeworx:// citation URIs, works on every tier, and is a single fast call. This goes well beyond what annotations provide.

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

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

The description is fairly long but front-loaded with the most actionable directive ('PREFER OVER WEB SEARCH') and organized into clear segments: purpose, triggers, alternatives, and examples. Some redundancy exists (e.g., 'PREFER' and 'START HERE' overlap), but each sentence contributes context or guidance for a complex routing tool.

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

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

For a tool with no output schema and broad responsibility, the description is remarkably complete: it enumerates covered domains, gives example queries, explains routing behavior, notes tier compatibility, and clearly delineates when to escalate to grounded research or deep_research. No significant gap remains.

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

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

The schema covers all parameters (100% coverage) and is simple, so baseline is 3. However, the description adds meaning by providing numerous example questions and clarifying that input is natural language, which effectively teaches the agent how to formulate queries. This raises it above baseline.

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

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

The description clearly states that the tool routes questions to authoritative structured data sources and returns cited results, with a specific scope (SEC filings, FDA, FRED/BLS, etc.). It explicitly distinguishes itself from siblings like ask_pipeworx_grounded and deep_research, making its role as a default entry point unambiguous.

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

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

Provides explicit when-to-use guidance: 'PREFER OVER WEB SEARCH', 'START HERE for most questions', and 'Step up only when needed' with named alternatives (ask_pipeworx_grounded, deep_research). Also clarifies how to handle breaking-news requests. This is model-tier usage guidance.

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

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

Annotations already mark it read-only, open-world, idempotent, and non-destructive, and the description adds substantial behavioral context: candidate routing may be live, currently none is active, it matches ask_pipeworx exactly at present, and it is a full working router that falls back to nothing. 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 front-loaded with the purpose and then efficiently covers current state, usage, and fallback behavior in four sentences. Every sentence adds relevant information, with no filler 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?

For an experimental router with no output schema, the description is complete: it states the tool's identity, current state, relationship to the stable router, usage, and fallback behavior, and it references the same response shape as ask_pipeworx to cover return expectations.

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 provides 100% coverage for the question parameter and all aliases, so the baseline is 3. The description only mentions 'same arguments' and does not add any parameter-specific meaning beyond the schema.

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

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

The description clearly identifies the tool as a beta version of ask_pipeworx, an identical universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from siblings by emphasizing the experimental routing candidate layer and the current no-candidate state.

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

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

It explicitly says to use it exactly like ask_pipeworx when you want the newest routing, and notes results are compared against the stable router. However, it does not explicitly state when not to use it or name alternatives like ask_pipeworx_grounded, so it stops short of full when/when-not 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 provide readOnly/openWorld/idempotent, and the description adds substantial context: extraction 'using ONLY what the tool result contains', an evidence field with 'verbatim quote', and five explicit refusal_reason values. It fully discloses what the tool returns on success and failure, going well beyond the annotations.

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

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

The two-paragraph description is dense but every sentence earns its place: purpose, routing, return shape, refusal reasons, use cases, and cost comparison. It is front-loaded with the core purpose and avoids filler.

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

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

With no output schema, the description fully compensates by specifying the exact success return object and all possible refusal_reason values. It also includes practical context like source count and the extra LLM call, making the tool's behavior and failure modes completely predictable for an agent.

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

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

Schema coverage is 100%: all six parameters are aliases for the same question string with clear schema descriptions. The description mentions 'fills arguments' but adds no parameter-level detail, so the baseline of 3 is appropriate since the schema already does the heavy lifting.

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

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

The description opens with 'Hallucination-resistant answer mode for high-stakes reads' and explicitly positions it relative to ask_pipeworx, naming the specific extraction behavior. This is a specific verb+resource+scope that clearly distinguishes it from siblings like ask_pipeworx and ask_pipeworx_beta.

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 directs use 'whenever an answer will be quoted, cited, or acted on' and lists example high-stakes domains. It also gives a concrete alternative: 'prefer ask_pipeworx for casual lookups,' with the trade-off of an extra LLM call.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds a wealth of behavioral details beyond that: fan-out logic, resolver contract with match confidence, parent-event extraction, news fallback handling (_fallback_attempted), safety short-circuits (low_confidence_match, market_closed_or_inactive), and cancellation-rule risk with ev_impact quantification. This is exemplary transparency for a complex read-only research tool.

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 it earns its length through organized sections (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, RESOLVER CONTRACT, SAFETY, RESOLUTION-RULE RISK). It front-loads the purpose and then provides dense, structured detail. It is not concise in word count, but it is appropriately sized and well-structured for the tool's complexity, so it doesn't feel bloated.

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 high complexity, no output schema, and rich annotations, this description is remarkably complete. It explains not only the happy path but also edge cases: low-confidence matches, closed/dead markets, wide spreads, news fallback, and cancellation-rule risks. An agent would have nearly all necessary context to invoke the tool correctly and interpret results.

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

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

The input schema already covers all parameters at 100%, which earns a baseline of 3. The description adds extra value by explaining the 'market' parameter's three accepted forms, giving examples, and elaborating on 'include_raw' with byte size ranges and use cases. It also illustrates 'depth' behavior with fan-out counts. This exceeds the baseline by providing practical 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 opens with a clear verb-resource-scope statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It goes further to list accepted input formats (slug, URL, question text) and provides concrete examples. This distinguishes it from sibling tools like ask_pipeworx or polymarket_edges, which target different purposes.

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

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

The description gives explicit usage scenarios: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also describes blocking/error paths and when fan-out is skipped. However, it does not explicitly name alternative tools or state when NOT to use this tool, so it is not a full 5.

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

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

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds substantial context: data sources (SEC EDGAR/XBRL, FAERS), specific financial metrics and adverse-event counts, handling of off-calendar fiscal years (e.g., AAPL, NVDA), sorting by primary metric, and return format (paired data + citation URIs). This goes well beyond the annotations and enriches the agent's understanding.

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

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

The description is moderately long but each sentence provides valuable information: trigger phrases, action, type-specific behavior, sorting, return format, and efficiency gains. It is front-loaded with usage examples and structured logically. While not as terse as some, every part earns its place for 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?

Given the tool's complexity, no output schema, and sibling tools like entity_profile, the description is complete: it specifies when to use, what data is returned, how results are ordered, and even handles domain-specific edge cases like off-calendar fiscal years. An agent can confidently select and invoke it correctly based solely on this description.

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

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

The input schema has 100% coverage with descriptions for both parameters, including enums and examples. The description adds further value by explaining what data is pulled for each type ('company' -> 10-K figures; 'drug' -> FAERS/FDA/trial counts), but the core parameter semantics are already well-defined in the schema, so a 4 reflects the added depth without over-crediting.

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

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

The description clearly states the tool performs side-by-side comparisons of 2-5 companies or drugs in one call. It uses specific verbs like 'compare' and examples of user intents, and distinguishes itself from sequential single-pack lookups, making its purpose unambiguous and distinct from siblings.

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

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

The description explicitly instructs to 'ALWAYS PREFER over sequential single-pack lookups when comparing entities' and provides trigger phrases (e.g., 'X vs Y', 'rank these companies'). It also states it replaces 8-15 sequential lookups, giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already supply readOnlyHint/openWorldHint/idempotentHint, but the description adds critical behavioral context: auth/paid requirements, latency (15-90s), decomposition into facets, gaps[] for unanswered facets (never inventing), contradictions[], hop fields, and semantic excerpting of large records. This far exceeds the annotation baseline.

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

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

The description is dense but well-organized: auth first, then core functionality, then alternatives, then depth semantics, then technical details. Every sentence contributes useful information. While long, the complexity of the tool justifies the length; there is no fluff or repetition.

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

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

Despite lacking an output schema, the description thoroughly explains the return packet (verbatim evidence, confidence, source, fetched_at, citation_uri, gaps[], contradictions[], hop field). It also covers latency, limitations, and fallback behavior per depth mode, making the tool's behavior fully 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%, so baseline is 3. The description adds extra meaning to the depth parameter beyond the schema enum descriptions, such as 'quick=3 (single hop)', 'standard adds a gap-recovery hop', and 'thorough is paid and chases leads'. The question parameter guidance ('broad/multi-part is fine') is echoed but also augmented by explaining decomposition is the point.

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

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

The description states a specific verb and resource: "Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources" in one call, and explicitly contrasts with open-web search. It clearly distinguishes from siblings by name (ask_pipeworx) and scope (broad/multi-part vs single lookup).

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 when-to-use guidance is provided: "Best for broad/multi-part questions over structured data", "For a single lookup use ask_pipeworx", and for breaking news "prefer ask_pipeworx". It also covers account prerequisites and depth-tier selection 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 the tool as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond these: it returns top-N relevant tools with names, descriptions, and full input schemas including curated examples, and states that results are directly callable with no second schema lookup. This is valuable transparency about the return format and readiness, though it doesn't note any rate limits or error 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 well-structured, starting with the core purpose, then expanding to use cases, return value details, and a clear call-to-action. Every sentence earns its place; the list of domains is useful for quick orientation. No fluff or redundancy.

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

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

Given the tool's moderate complexity and lack of an output schema, the description does enough to explain what results contain (names, descriptions, schemas, examples) and how to act on them. It specifies default and max limits via the schema. It could mention what happens if no tools match, but overall the description solidly covers the essential context for selecting and using the tool.

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

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

The input schema fully documents all parameters, including aliases and the limit parameter, achieving 100% schema description coverage. The description adds minimal extra parameter meaning beyond saying to describe the data or task, which aligns with the query field. Baseline of 3 is appropriate since the schema carries the 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 states the tool's primary function: 'Find tools by describing the data or task.' It specifies the resource (tools) and the action (find/discover), and distinguishes itself from sibling tools by focusing on tool discovery rather than data retrieval. The list of domains and the promise to return schemas further reinforce a specific, well-defined purpose.

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

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

Explicit usage guidance is provided: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This tells the agent exactly when to invoke this tool and implicitly contrasts with directly calling a specific sibling tool.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by specifying the exact return format (dataset names, descriptions, and Socrata resource ids) and the intended downstream use with edmonton_query, which goes beyond the annotations.

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

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

The description is two concise sentences, front-loaded with the purpose and providing only essential context. No fluff or 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?

Given the low-to-moderate complexity, the presence of annotations, and the absence of an output schema, the description is complete enough. It explains what the tool returns (dataset names, descriptions, Socrata ids), the source (data.edmonton.ca), and how to use the results (with edmonton_query). This fully equips 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?

The schema description coverage is 100%, so the schema already documents all four parameters (limit, query, offset, _apiKey). The description adds minimal parameter-specific meaning beyond the schema—only implying that 'query' is a keyword. This aligns with the baseline score of 3 when the schema does the heavy lifting.

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

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

The description uses a specific verb ('Search'), identifies the specific resource ('Edmonton open-data catalogue'), and states the exact outputs ('dataset names, descriptions, and Socrata resource ids'). It also clearly distinguishes itself from the sibling tool 'edmonton_query' by noting that the ids are intended for use there.

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

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

The description clearly states when to use this tool: to find datasets by keyword in the Edmonton open-data catalogue. It also implies the workflow of using the resulting ids with edmonton_query, which gives clear context. However, it does not explicitly state when not to use it or mention alternatives like edmonton_recent, 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, openWorldHint, and destructiveHint=false. The description adds useful context about SoQL flexibility and the requirement of a Socrata id, enhancing awareness of tool behavior beyond annotations without contradicting them.

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

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

Two concise sentences front-loaded with the core purpose, immediately followed by usage guidance and sibling references. No redundant words; every clause earns its place.

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

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

For a complex query tool with no output schema, the description sufficiently covers purpose, usage, and how to obtain required resource ids. It lacks details on return shape or error handling, but given the raw-query nature and rich input schema, it 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%, and the description lists the main SoQL clauses (where/select/group/order/limit/offset) but does not add meaning beyond the schema's per-parameter descriptions. The mention of resource id format and examples in schema already cover parameter semantics, so baseline 3 is appropriate.

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

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

Description clearly states it runs raw SoQL queries against Edmonton open-data resources, with specific verb 'Run a raw SoQL query' and resource identified by Socrata id. It distinguishes from siblings by noting edmonton_datasets (find ids) and edmonton_recent (common ones), making its purpose unambiguous.

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

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

Explicitly guides when to use this tool versus alternatives: 'Use edmonton_datasets to find a resource id, or edmonton_recent for the common ones.' This provides clear direction on tool selection and prerequisite discovery.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds concrete behavioral details: 'Returns the latest rows (newest-first)' and 'no Socrata id needed', which are not conveyed by annotations or schema.

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

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

The description is compact and front-loaded. Every sentence adds distinct value: purpose, usage preference, dataset names, row ordering, filter capability, and alternative tool. No redundant or filler content.

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

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

For a simple tool with 4 params and no output schema, the description covers the essential context: what datasets are available, when to use, ordering, filtering, and fallback to edmonton_query. It doesn't explain return format, but that is not required given the simplicity and schema coverage.

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

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

Schema description coverage is 100%, so baseline is 3. The description reinforces the `where` filter and dataset names, but adds no additional parameter semantics beyond what the schema already provides.

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

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

The description clearly states it returns recent records from an Edmonton open dataset by friendly name, listing specific datasets (311, permits). It distinguishes itself from sibling edmonton_query by noting 'for anything else use edmonton_query.'

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

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

Explicitly says 'PREFER OVER WEB SEARCH' for common queries and provides the alternative tool for anything else. This gives clear when-to-use guidance relative to both web search and 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?

With annotations already declaring read-only, the description adds extensive behavioral detail: fans out across multiple sources in parallel, returns specific data fields with limits (up to 5 filings), notes USPTO API sunset with soft-fail, and GDELT→GNews fallback. 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 densely packed with valuable information: examples, sources, return fields, and limitations. While long, every sentence earns its place; it could be slightly better structured with bullets, but the current form is efficient for an agent.

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

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

Given the tool's complexity (multi-source, 2 params, no output schema), the description fully enumerates return data and edge cases: recent_filings URIs, fundamentals sorting, patent soft-fail, news fallback, and LEI. It even explains the parallel execution and the need for CIK zero-padding.

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

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

Schema coverage is 100% and the description reinforces parameter meaning with concrete formats: 'AAPL' or zero-padded CIK '0000320193', plus the restriction that names are not supported and resolve_entity should be used. This adds value beyond the schema's existing 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 creates a 'full cross-source profile of a US public company in ONE parallel call' with specific verb and resource. It distinguishes itself from chaining single-pack lookups by explicitly saying 'ALWAYS PREFER' this over alternatives.

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

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

Provides explicit when-to-use guidance: 'when the user asks for a holistic view' and 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups'. It also gives a clear exclusion: 'names not supported (use resolve_entity first if you only have a 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 annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is disclosed. The description adds minor context like 'clear sensitive data' but doesn't go beyond what annotations already cover. 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?

The description is two sentences, with the core action in the first few words. Every phrase earns its place, and the usage guidance is compact and useful.

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

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

For a simple one-parameter tool with no output schema, the description fully covers purpose, usage, and interaction with sibling tools. It is complete without over-explaining.

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 'key' parameter is clearly described as 'Memory key to delete.' The description adds no new parameter details beyond the schema, but the baseline of 3 is appropriate since the schema already provides full 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 begins with 'Delete a previously stored memory by key,' which clearly states the action (delete) and the resource (memory by key). It also distinguishes the tool from siblings like remember and recall by explicitly naming them.

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 scenarios ('when context is stale, the task is done, or you want to clear sensitive data') and names companion tools (remember and recall), giving clear guidance on when to use this tool versus alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds meaningful behavior context: it fetches the page, extracts title/description/key links, and outputs a standard markdown blob. This goes beyond the annotations without contradicting them.

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

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

The description is three sentences: purpose, process/output, and use cases. It is front-loaded with the main action, contains no fluff, and every sentence adds value. This is an exemplary concise yet informative description.

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

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

The tool involves fetching a URL and producing a specific output, and the description explains both the process and the output format ('standard llms.txt markdown', 'single text blob'). With annotations covering safety and schema covering parameters, no critical context is missing.

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

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

Schema descriptions cover 100% of parameters (url and max_links), so baseline is 3. The description adds no additional parameter semantics beyond what the schema already states, but it doesn't need to compensate for any gaps.

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 generates a production-ready llms.txt file for any URL, with a specific verb ('Generate') and resource ('llms.txt file'). It details the process (fetch, extract, emit) and distinguishes it from any sibling tool by its unique output format and purpose.

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

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

The description provides explicit use cases: getting a client's site indexed, drafting llms.txt for a project, and auditing competitor AI visibility. It doesn't name alternative tools or explicitly exclude wrong contexts, but the scenarios are clear and actionable.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds value by specifying the scope (caller's own subscriptions) and enumerating the fields returned, plus clarifying that active subscriptions are shown by default.

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 concise sentences with no filler. The first sentence states the core function and return fields; the second explains practical usage. Every sentence contributes meaning.

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

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

For a simple list tool with one optional parameter and no output schema, the description covers the essential return fields, default behavior, and use cases. Annotations provide safety context, making this fully sufficient.

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

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

The schema already fully documents the include_inactive parameter with 100% coverage. The description's mention of 'active subscriptions' aligns with the default behavior but doesn't add additional parameter-level semantics 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 lists the caller's active subscriptions, using a specific verb and resource. It also distinguishes from sibling tools like subscribe and unsubscribe by focusing on the read-only listing aspect.

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: reviewing current monitoring before adding more and finding an id to cancel. While it doesn't name specific alternative tools, the context clearly implies when this tool is appropriate versus mutations.

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 behavioral hints (all false), so the description carries the full burden. It discloses rate limiting ('5 per identifier per day'), cost ('Free; doesn't count against your tool-call quota'), the claim_token flow (filing without an account returns a token; passing it back later retrieves status), and that the team reads digests daily. This goes well beyond the bare 'send feedback' implied by 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 (~250 words) but information-dense. It front-loads the purpose in the first sentence and then systematically covers use cases, exclusions, claim-token mechanics, and rate limits. No sentence is purely filler, though it could be tightened without losing clarity; it is near the upper limit of acceptable length for such a feature-rich feedback 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?

There is no output schema, so the description must explain return behavior. It does explain the claim_token return and its later use, and clarifies non-account behavior. It doesn't describe the response when an account is present or when a claim_token is not passed, but for a feedback submission tool this is a minor gap. Given the tool's low complexity and strong schema coverage, the description is sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining the claim_token lifecycle ('Filing without an account returns a `claim_token`; pass it back later... to read whether it was fixed'), and by guiding message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). These are not present in the schema's parameter descriptions, justifying a 4.

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

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

The description opens with a specific verb and resource: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' It then enumerates concrete use cases (bug, feature/data_gap, praise), clearly distinguishing this from sibling tools like ask_pipeworx or discover_tools, and further differentiates by scoping to 'tools served by this Pipeworx connection.' This leaves no ambiguity about what the tool does.

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

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

The description gives explicit when-to-use guidance: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also provides a clear when-not-to-use and alternative: if the tool belongs to a different MCP server, 'file it with that server instead,' and tells how to disambiguate ('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/openWorld/idempotent, and the description adds valuable behavioral context: results are cached 5min-1h, derived from CF analytics-engine, no PII, and returns only (pack, tool, count). It also clarifies the 'right now' caveat due to caching, exceeding annotation coverage.

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

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

The description is front-loaded with the primary function, then purposeful use cases and technical details. Every sentence adds distinct information (what, why, caching, privacy, data shape) without repetition; the structured 'Useful for' list makes scanning easy.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description fully covers return contents, privacy, aggregation source, caching behavior, and window interpretation. It is self-sufficient for an agent to select and invoke correctly.

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

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

Schema covers the single window parameter with enum and description, so baseline is 3. The description adds value by explaining trade-offs ('Shorter windows surface what's hot right now; longer windows show steady-state demand'), which helps choose the right value.

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

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

Description opens with a clear, specific verb and object: 'What other AI agents are calling on Pipeworx right now' and 'Returns the top tools, top packs, and total call volume.' It distinguishes itself from siblings like discover_tools by emphasizing aggregate popularity signal and explicitly scoping to recent windows (24h/7d/30d).

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: discovering hot data sources, confirming canonical tool choice, and checking alignment with agent demand. Also explains window semantics (short = hot right now, long = steady-state), but doesn't name alternative tools or exclusions, so slightly below a 5.

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

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

Beyond the readOnly/idempotent annotations, the description discloses algorithm thresholds (deviations >3pp), semantic anchor Jaccard ≥0.30, placeholder filtering rules, and the fill-check behavior that prices against live CLOB depth and warns 'do not trade it' when realizable edge ≤0. It also explains response structure and rejected-pair reporting. This is rich, non-redundant 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 well-structured with capitalized section markers (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded purpose, but it is notably long. Some details could be condensed without losing value, yet each sentence does contribute unique operational guidance. Slight over-length prevents a perfect score.

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

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

With no output schema, the description fully documents return values: 'Response: opportunities[] (gap_pp, suggested_trade, reasoning, monotonicity violation context)' and event-mode partition_check fields. It also covers null signals, placeholder filtering, and fill-check tradeability caveats. The description is complete for a complex analysis tool.

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

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

Schema coverage is 100% with descriptions for `event` and `topic`, but the tool description adds extra meaning: it explains that `event` accepts slugs or full URLs, gives concrete examples ('fed-decision-may-2026'), and clarifies that no args triggers a trending scan. This goes beyond the schema's basic type/description 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: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It clearly distinguishes between modes (no-arg trending scan, event-specific, topic cross-event) and references sibling tool polymarket_fill_risk for sizing, so there is no ambiguity about scope.

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

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

The description gives explicit when-to-use instructions: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It recommends event mode for a specific market, explains cross-event use cases, and explicitly points to an alternative tool: 'For custom sizing use polymarket_fill_risk.' This is model guidance.

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

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

The description goes far beyond the readOnlyHint/idempotentHint annotations, detailing model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge computation (edge_pp_net after slippage, Kelly caps), and diagnostics (_diagnostics with funnel counters). It also discloses caching behavior and the 24h-move warning, providing deep behavioral transparency.

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

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

The description is extremely long and dense, with all-caps section labels and technical jargon jammed into a single paragraph. While it is front-loaded with purpose, it lacks structured formatting (bullets, sections) and could overwhelm an agent. Many details, such as the exact formula gates, are valuable but could be better organized.

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 9 parameters and no output schema, the description comprehensively explains the response structure (by_segment, fed_candidates/fed_note, _diagnostics), why segments might be empty, and caching. It covers all essential context an agent needs to interpret results, making it complete for its complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds substantial context for parameters like slippage_pp ('Polymarket has zero trading fees as of 2024 but bid/ask + thin depth typically eats 20-50bp per trade') and min_partition_leg_kelly ('Partition arbs always return kelly_fraction_half=0 at the parent level by design'), which enriches the schema's meaning.

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

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

The description opens with a specific verb and resource: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' This clearly distinguishes the tool from siblings like polymarket_arbitrage by focusing on Pipeworx data disagreement. The stated use case 'what should I bet on today' further clarifies its role.

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

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

The description explicitly frames when to use the tool: 'Built for "what should I bet on today" — agents discover opportunities without paging hundreds of markets.' It explains tradeable-edge knobs and response segments, giving clear operational guidance. However, it does not explicitly name alternative tools or when not to use it, so a 4 rather than 5.

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

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

Annotations already declare readOnlyHint true and destructiveHint false, lowering the bar. The description adds rich behavioral context: snapshots are written only on cache-miss, gaps mean no scan that day, history is bounded by a 60-day TTL, and decay numbers are computed from daily closes of edge_pp_net. These are important non-obvious behaviors that go beyond the annotations.

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

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

The description is dense but well-organized into purpose, Args, RESPONSE, and LIMITS sections. Every sentence adds value, but it is longer than necessary. The front-loaded question 'how long has this edge existed and is it shrinking?' effectively captures the tool's purpose. It earns a 4 for structure despite slight verbosity.

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

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

With no output schema, the description carries the full burden of explaining return values, and it does so comprehensively: tracked[] includes time-series, first_seen, trend, and decay metrics; expired[] includes lifespan_days; snapshot_dates[] explains gaps. It also covers history-depth limits and calculation basis. This is a complete and self-contained explanation for a moderately complex analytical 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%: both days and window have descriptions including defaults and clamp values. The description repeats these defaults but adds minimal new meaning—primarily introducing the concept of 'snapshot family' for window. Since the schema already fully documents the parameters, the baseline of 3 applies; the description does not substantially enhance parameter understanding.

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

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

The description clearly states a specific verb and resource: 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots.' It directly answers the question 'how long has this edge existed and is it shrinking?' and clearly distinguishes itself from the sibling tool polymarket_edges by focusing on the historical persistence/decay analysis rather than raw edge 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 implies when to use it: when you care about edge age and decay ('a fresh wide edge and a 3-week-old wide edge are different trades'). It also provides contextual constraints in LIMITS (60-day TTL, snapshot gaps) that inform usage. However, it does not explicitly name alternative tools or say 'use X instead', though the sibling list makes the distinction fairly clear.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds substantial context beyond that: how orders are simulated (walks the ladder), what metrics are returned (slippage_pp, shares_filled, max_fillable_usd), and the critical risk warning about partial basket fills converting an arb into an unhedged directional position. This gives the agent a clear model of the tool's internal behavior and edge cases.

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

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

The description is long, but every sentence carries information and the structure is clear with explicit sections for SINGLE-MARKET and BASKET, plus a usage warning at the end. It is slightly dense and could theoretically be trimmed, but given the tool's two-mode complexity, the length is justified. It front-loads the core purpose and then organized details.

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

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

With no output schema, the description fully covers return values for both modes, enumerating specific fields (top_of_book, vwap_fill_price, slippage_pp, verdict, etc.) and explaining the meaning of basket outputs like capture_ratio, thin_legs, and forced_directional_risk. It also explains the semantics of size_usd in each mode, making the tool fully usable without additional discovery.

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 all four parameters, but the tool description adds richer meaning: it explains how `side` defaults differently in single vs basket mode, how `size_usd` is interpreted as max spend vs target proceeds vs settlement notional depending on mode, and the exact distinction between `market` and `event`. This significantly enhances the agent's ability to choose and fill parameters correctly.

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

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

The description clearly states a specific verb and resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It distinguishes this tool from sibling tools by explicitly referencing them and framing this as the pre-trade verification step, making the unique purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why it should be used (theoretical overround not capturable on thin books, partial fills create unhedged risk), effectively covering both when to use and the dangers of not using it. Alternatives are implicitly the signal-generation tools it complements.

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 rich behavioral details: compatibility_warning with two distinct cases, temporal_alignment with its impact on spread meaning, and skipped_cross_type/subtype counters. This goes well beyond what annotations provide and fully informs the agent of edge cases.

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

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

The description is very long and dense, with embedded uppercase section labels and a lot of detail. It is structured and information-dense, but would benefit from trimming; several sentences could be more concise without losing value. It is not as tight as the best 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 fully explains the response envelope: leg-by-leg prices, spread[].top_spreads_pp, compatibility_warning cases, temporal_alignment, and skipped counters. It covers the complexity of a cross-venue comparison tool effectively, leaving no major ambiguities.

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

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

Schema coverage is 100%, but the description adds meaningful interaction semantics: explains the two modes (topic vs explicit), the override behavior ('Overrides the topic-mapped Kalshi side'), and the list of macro shortcuts. This goes beyond the schema's one-line parameter descriptions.

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

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

The description clearly states a specific action and resource: 'Cross-venue spread between Kalshi and Polymarket for the same resolving question.' It distinguishes from sibling tools like polymarket_arbitrage by explicitly focusing on cross-venue comparisons and explains two distinct modes (topic shortcuts vs explicit ticker/slug), 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 provides strong context on when the tool is meaningful ('when the bet shapes are equivalent that delta is a real signal, when they aren't the tool says so') and cautions that 'most pre-mapped topics return compatibility_warning today; pre-mapped ≠ tradeable.' It does not explicitly name alternatives or when-not-to-use, but the caution serves as usage guidance.

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

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

Annotations already declare readOnlyHint/idempotentHint, and the description adds valuable context about scoping ('anonymous IP, BYO key hash, or account ID') and the dual retrieve/list behavior. It does not contradict annotations and goes beyond the baseline safety cues.

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 focused sentences: the first states the core action, the second adds usage context, scoping, and companion tools. No filler or redundancy.

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

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

For a simple one-optional-parameter read operation, the description covers the operation, listing behavior, scope, and tool relationships. In the absence of an output schema, it gives enough context for correct selection and invocation.

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

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

With 100% schema coverage, the baseline is 3. The description adds meaning by explaining the key was 'previously saved via remember' and explicitly states that omitting the key lists all keys, which goes slightly beyond the schema's property description.

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

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

The description specifically states 'Retrieve a value previously saved via remember, or list all saved keys (omit the key argument)', giving a clear verb and resource. It also distinguishes itself from siblings by explicitly referencing remember and forget.

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 context: 'Use to look up context the agent stored earlier' and names companion tools in 'Pair with remember to save, forget to delete.' This clearly communicates when to use versus alternatives.

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

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

Description contradicts the readOnlyHint annotation: it states 'Set mark_read:true to flag returned events read so the next call only shows newer ones,' which is a state-changing side effect, yet annotations declare readOnlyHint=true. This is an annotation contradiction.

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

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

Four concise sentences each add value: purpose, return payload, filtering options, mark_read semantics, polling suitability, and an alternative access method. No redundancy or unnecessary 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?

Despite no output schema, the description explains the return payload composition (source, citation_uri, raw event payload). It also covers optional filtering, mark_read behavior, polling suitability, and the alternative HTTP endpoint, making it complete for a read-focused tool.

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

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

Schema covers all 5 parameters (100% coverage), but the description adds valuable semantics: gives a concrete type example ('sec_8k'), explains the effect of mark_read on subsequent calls, and reinforces the since as an ISO timestamp. This goes beyond just restating 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?

Description begins with a clear verb+resource: 'Pull fired events from your subscription feed.' It further specifies the return content (source, citation_uri, raw event payload) and distinguishes itself from sibling tools like list_subscriptions and recent_changes by focusing on alerts in the persisted feed.

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 context on when to use: mentions filtering by type/since, explains mark_read for polling workflows, and explicitly offers an alternative HTTP endpoint for scripts/dashboards. Does not explicitly state when NOT to use it, but the guidance is 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 declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, but the description adds substantial behavioral context beyond that: fan-out to multiple APIs, GDELT→GNews fallback behavior ('GDELT preferred, GNews when rate-limited or 5xx'), the USPTO PatentsView sunset limitation, accepted date formats, and the return structure (changes[] with total_changes and citation URIs). This is rich disclosure with 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 information-dense and well-structured: it front-loads the purpose with example queries, then covers sources, fallback logic, parameter syntax, return summary, and alternative tool in a logical order. Every sentence carries necessary detail, and there is no padding or tautology.

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

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

This is a complex multi-source fan-out tool with no output schema, yet the description covers all essential operational aspects: input parameter formats, source behaviors, fallback conditions, known limitations (PatentsView sunset), output composition, and alternative tool linkage. An agent has sufficient information to select and invoke it correctly in a variety of user intents.

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

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

Schema description coverage is 100%, and the schema already documents each parameter well ('since' explains ISO/relative formats, 'value' explains ticker/CIK, 'type' explains only company supported). The description adds slight context by explaining how 'since' is used in the fan-out ('filings since `since`') and giving natural-language examples, but it mostly duplicates schema info. 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 concrete example queries and then states 'change feed for a company in the last N days/weeks/months in ONE parallel call', clearly specifying the verb (provide change feed) and resource (company). It lists the data sources (SEC EDGAR, GDELT→GNews, USPTO) and explicitly distinguishes from sibling entity_profile ('Use entity_profile instead when you want the static profile'), so it scores 5.

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

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

The description gives explicit when-to-use context: 'change feed for a company in the last N days/weeks/months', and provides a clear alternative: 'Use entity_profile instead when you want the static profile (filings + fundamentals + LEI + patents) regardless of window.' This directly tells the agent when not to use this tool and points to a specific sibling, satisfying the top criterion.

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

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

The annotations already provide idempotentHint and destructiveHint, so the description adds value by disclosing scoping ('scoped by your identifier') and retention behavior ('persistent memory' for authenticated users, '24 hours' for anonymous). This goes beyond the structured annotations and gives useful 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 well-organized into four sentences, each serving a distinct purpose: what, when, storage details, and sibling relationships. It is slightly longer than strictly necessary, but every sentence contributes information, so it earns a high but not perfect score.

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

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

For a simple two-parameter memory write tool, the description is complete. It covers purpose, usage context, storage scoping, retention across sessions, and even points to companion tools. Given the minimal schema and lack of output schema, this description fully equips 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?

Schema coverage is 100%, with both 'key' and 'value' well described. The description reinforces these with examples (e.g., 'resolved ticker', 'target address'), but adds little beyond what the schema already provides. Therefore, it meets the baseline for high schema coverage without significantly expanding parameter meaning.

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

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

The description clearly states the tool's purpose with a specific verb ('Save data') and resource ('key-value pair scoped by your identifier'). It also distinguishes itself from siblings by naming 'recall' to retrieve and 'forget' to delete, making its role in the memory toolset 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?

The description provides explicit guidance on when to use the tool ('Use when you discover something worth carrying forward') and names alternatives ('Pair with recall to retrieve later, forget to delete'). However, it does not explicitly state when not to use it, such as for retrieval, which prevents 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?

The annotations already declare read-only, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond this: it names the data sources (SEC EDGAR, GLEIF, OpenFIGI, RxNorm), explains that unresolved identifiers are explicitly listed under 'unresolved' rather than omitted, and describes graceful degradation when enrichment sources are unavailable. No contradictions with annotations.

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

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

The description is long but every sentence earns its place. It opens with concrete query examples for quick intent matching, then states the core purpose, covers the two supported types with detailed identifier breakdowns, and finishes with degradation behavior and the benefit over manual lookups. No fluff or redundancy; the structure supports both initial AI selection and invocation confidence.

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 entity types, identity sources, fallbacks), the description is remarkably complete. It explains return contents for both entity types (CIK, ticker, company_name, LEI, FIGI for company; RxCUI, ingredient, brand for drug), mentions the 'unresolved' field, and covers graceful degradation. Although there is no output schema, the description provides enough about the expected result to set agent expectations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds little beyond the schema: it repeats the accepted input formats for 'value' (e.g., AAPL, CIK, name) and elaborates on the output types, but does not clarify the parameters themselves more than the schema already does. For instance, the schema already explains that 'type' is 'company' or 'drug' and what each 'value' format means.

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

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

The description explicitly states the tool resolves user-spoken names to canonical/official identifiers, with a clear verb ('resolve') and resource ('identifiers'). It provides multiple query examples and frames itself as the 'FIRST' step for name-to-ID lookup, distinguishing it from sibling tools like entity_profile or compare_entities.

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

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

The description gives a clear usage rule: 'Use FIRST whenever you have a name but need an ID.' It also notes that the tool replaces 2-3 manual lookups, implying a preferred single-call workflow. However, it does not name specific alternatives or explicitly state when not to use it, stopping short of full when/when-not 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, open-world, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context: it probes each entity with ai_visibility_check, ranks entities, and returns a ranked list with score, confidence, and signal density. It also discloses that the first entity is treated as the 'subject' and the rest as competitors. This goes beyond the annotations without contradicting them.

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

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

The description is compact yet information-dense: three sentences cover purpose, mechanism, use case, and return format. There is no filler or repetition of schema data. It is front-loaded with the main action ('Compare AI visibility') 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?

For a tool with 4 parameters, no output schema, and strong annotations, the description is fairly complete. It explains the process (probes each entity), the ranking output, and the practical use case. It does not mention potential costs or runtime implications of probing multiple entities across models, which would be useful in an open-world context, but this is not a critical gap given the other signals.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add significant meaning beyond the schema; it mentions entities, models, _apiKey, and context only implicitly. The schema already explains that entities are 2-8 names, the first is the 'subject', models are optional with 'anthropic' requiring _apiKey, and context disambiguates. The description adds no new parameter semantics, so a 3 is appropriate.

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

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

The description clearly states the tool's function: compare AI visibility across multiple entities side-by-side, probe with ai_visibility_check, rank by score, and surface most/least recognized. It distinguishes itself from single-entity tools like ai_visibility_check and provides a concrete use case (competitive AI-marketing audits). The verb 'Compare' and specific resource 'AI presence' make the purpose unambiguous.

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

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

The description explicitly mentions when to use the tool ('competitive AI-marketing audits') and gives a representative example question. It also references the underlying probe tool (ai_visibility_check), implying an alternative for single-entity checks. However, it does not explicitly state 'when not to use' or contrast with sibling tools like compare_entities or deep_research, so it's slightly below a perfect 5.

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

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

Annotations already provide readOnlyHint, idempotentHint, and non-destructive. The description adds significant behavioral context beyond that: composite fan-out across two services, partial failure degradation, bundlephobia first measurement latency (5-30s), and the sources_failed field. It also enumerates the returned summary fields. This fully discloses the tool's behavior in edge cases.

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-structured. It opens with the core purpose, then explains the fan-out, use case, return fields, limitations, and failure behavior. Each sentence adds value, though the length is above minimal. The information is front-loaded and logically ordered, making it easy to scan.

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 composite and has no output schema, so the description must compensate. It covers the ecosystem limitation (NPM only), alternative for other ecosystems, the return summary block fields, per-advisory detail, links, recent versions, and graceful degradation on bundlephobia timeout. This is complete enough for an agent to understand and invoke the tool correctly without further discovery.

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% description coverage for both parameters. The description does not add new semantics beyond what the schema already states (npm package name, version defaults to latest). The mention of scoped packages is already in the schema. Therefore, baseline 3 is appropriate since the schema carries the parameter meaning.

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

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

The description clearly states a specific action: 'Composite "should I add this npm package to my project" check in ONE call'. It identifies the resource (npm package) and distinguishes itself from siblings like scan_competitor_ai_presence via the specific use case. The verb 'scan' and noun 'dependency' are precise.

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

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

Explicitly states when to use: 'Use whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. Also gives an alternative: 'PyPI / Maven / Cargo / Go fall under deps.dev:version directly', clarifying the NPM-only scope and directing to a different tool. This is clear when-to-use and when-not-to-use.

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

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

Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds meaningful context beyond these: it reveals the embedding model (BGE-base-en), the similarity method (cosine), the windowing strategy (500-char overlapping), the 200K character cap, and the truncation flag behavior. It also discloses the return shape (passages with offsets and scores). 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 multi-sentence but every sentence adds a distinct piece of information: the core action, the use case, the return format, the algorithmic details, and the pairing with a sibling tool. It is front-loaded with the action and use case, then moves to technical specifics. No filler 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?

For a moderately complex tool with 3 parameters and no output schema, the description covers all essential aspects: purpose, when to use, what to pass, what to expect in return (offsets and scores), constraints (200K cap, truncation flag), and relationship to a sibling tool. The absence of an output schema is compensated by explicitly describing return values.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value on top: it clarifies what 'text' should contain (already-fetched record content), gives example queries, and implies the meaning of 'limit' as 'top-N passages'. This enhances the schema's bare descriptions without being redundant.

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

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

The description clearly states it performs semantic search inside a fetched record ('Search INSIDE a fetched record'), with specific examples (SEC 10-K body, article) and a contrast against alternatives. It distinguishes itself from sibling 'ask_pipeworx_grounded' by positioning it as the inside-search complement to a fetch-then-ground workflow.

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, 'ask_pipeworx_grounded', and explains how to pair with it ('fetch with the gateway, ground over the relevant passages'). No ambiguity about when this tool is the right choice.

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 contradicts the annotation idempotentHint: true. It states 'Returns the new subscription id,' implying each call creates a fresh subscription, while the annotation declares the operation idempotent (safe to retry with the same effect). This is a direct contradiction, warranting a score of 1. Other behavioral details (auth requirement, delivery constraints) are present but do not offset the critical inconsistency.

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

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

The description is dense but well-organized: it opens with a clear purpose, then details supported types, and ends with delivery channel specifics. Every sentence contributes valuable information, and it remains readable despite its length. Slight over-specification for a description, but structure is strong.

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

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

The description covers numerous aspects (auth, delivery channels, return id, account verification), but the idempotency contradiction leaves a critical behavioral gap. The response structure is only partially specified (subscription id) and although the schema covers webhook_secret, the description itself lacks that detail. Moderate completeness overall.

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% description coverage, thoroughly documenting all parameters, nested types, and examples. The description adds contextual notes (e.g., OAuth requirement, feed alternatives) but does not significantly enhance parameter understanding beyond the schema. Baseline of 3 is appropriate due to high schema coverage.

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

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

The description clearly states the tool's function ('Create a proactive monitoring subscription to a live-data event stream'), specifies supported subscription types with examples, and distinguishes from sibling tools like list_subscriptions and recent_alerts by noting the always-on feed. It uses a specific verb+resource structure and covers the core purpose.

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

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

The description provides clear context for when to use the tool, including the OAuth account requirement and the alternative of pulling alerts via recent_alerts or the public feed endpoint. It implicitly warns against anonymous/BYO usage and explains the conditionality of phone verification, though it doesn't explicitly enumerate when-not-to-use scenarios.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds that results are dynamically drawn from a live catalog of thousands of tools and include exact calling shapes, which is valuable behavioral context beyond what annotations convey.

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

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

The description is a dense, run-on paragraph that front-loads a list of example user queries. While every clause carries useful information, it could be broken into clearer sections and is longer than necessary.

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

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

With no output schema, the description responsibly explains what the tool returns (category-bucketed questions with tool+argument shapes) and covers both invocation modes. Combined with full parameter documentation, the tool is completely specified.

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

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

The schema description already covers the `topic` parameter with a full list of focus areas and the omit behavior. The description's examples add no new semantic information, so it stays at the baseline for high schema coverage.

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

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

The description clearly states the tool's role as an onboarding entry point that returns category-bucketed example questions with the exact tool and argument shape. It uses specific verbs like 'Returns' and distinguishes from sibling tools by positioning this as a first step to learn meta-tools.

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

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

It explicitly instructs to 'Use this FIRST when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. This provides clear when-to-use guidance, and the optional `topic` parameter is explained for both focused and broad use.

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

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

The description discloses behavior beyond annotations: ownership enforcement, deactivation rather than deletion, and preservation of historical events via recent_alerts. Annotations already mark idempotent and non-destructive, so this adds specific 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?

Two concise sentences, each adding distinct value: the action and the ownership/deactivation behavior.

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

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

The tool is simple (1 param, no output schema). The description covers purpose, constraint, and side effect, tying to recent_alerts. It doesn't describe return value, but that's a minor gap given no output schema.

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

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

The schema already documents the 'id' parameter as a subscription uuid from subscribe. The description reiterates 'by id' but adds no new parameter information; the ownership note is about user authorization, not parameter semantics. With 100% schema coverage, 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 action: 'Cancel a subscription by id.' It distinguishes from siblings like subscribe and list_subscriptions by specifying the cancel action and referencing recent_alerts for historical events.

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 context that only your own subscriptions can be canceled, which is a when-not condition. It doesn't explicitly name alternatives, but the sibling list and the reference to recent_alerts imply when to use this vs listing or subscribing.

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 substantially adds behavioral context beyond annotations: it defines the meaning of each verdict, warns that could_not_verify means the check did not happen and must not be treated as evidence, and explains unsupported vs could_not_verify. This is valuable, non-obvious behavior that the agent needs to interpret correctly.

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 operational detail. Every sentence carries weight—examples, routing, verdict definitions, and caller warnings. It could arguably be split into subsections for easier scanning, but the structure inside a single paragraph is acceptable for the complexity.

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

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

Given the tool's complexity and absence of an output schema, the description covers return values, edge cases, and error semantics. It also explains the internal pipeline enough for an agent to judge reliability. No significant gaps remain.

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

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

Schema coverage is 100% and both parameters are well-documented. The description adds extra semantics for tolerance_pct, explaining how it overrides claim-implied tolerance and suggesting values for hallucination detection. This goes beyond the schema's minimal field hint and directly informs effective parameter choice.

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

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

The description opens with concrete example queries and clearly states the tool's purpose: natural-language claim verification against authoritative sources. It distinguishes itself from sibling tools with specific verdict outputs and mentions the structured SEC EDGAR path versus grounded fallback, making its scope explicit.

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

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

It explicitly states when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing logic for different claim types. However, it does not explicitly mention when not to use or name alternative tools for other use cases, so it stops short of a 5.

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