Censtatd Hk

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds: default model selection, that _apiKey is passed through to Anthropic (cost implication), and return structure. No contradictions.

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

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

Description is a single paragraph but efficiently conveys purpose, defaults, usage, and return format. Could be slightly more structured, but no wasteful sentences.

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

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

Given no output schema, description adequately specifies return structure (per-model fields + combined view). Covers all 4 parameters, default behavior, cost note for Anthropic. Complete for tool 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%, baseline 3. Description adds value by providing examples for entity, listing supported models, clarifying _apiKey usage ('passed straight through'), and explaining context purpose. Exceeds minimal schema info.

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 states specific verb ('probe'), resource ('LLMs'), and outcome ('score visibility 0-100 per model'). Clearly distinguishes from siblings like deep_research or entity_profile by focusing on LLM knowledge scoring for brands/topics.

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?

Description provides usage context: 'AI-marketing audits, pre-launch brand checks, competitive monitoring'. Explains default model and when to provide _apiKey for Anthropic. Does not explicitly exclude alternatives but implies appropriate 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 readOnly, openWorld, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond those hints: it routes to sub-tools, fills arguments, returns structured answers with stable pipeworx:// citation URIs, and is described as 'one fast call' that works on every tier. It does not contradict the annotations.

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

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

The description is long but intentionally front-loaded with the 'PREFER OVER WEB SEARCH' directive and organized with examples and escalation paths. Every sentence earns its place given the tool's role as a central router; slight redundancy ('START HERE' plus 'default entry point') is minor.

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

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

Despite having no output schema, the description explains the result format (structured answer with pipeworx:// citations), covers a wide range of example queries, and provides enough context about when to escalate. It is complete for an AI agent deciding whether to select this tool and how to phrase the input.

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% (question plus five aliases), so the baseline is 3. The description adds examples and clarifies that the parameter is a natural-language question, but it does not add formatting, length, or disambiguation details beyond what the schema already provides.

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

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

The description clearly states the tool's function: it routes questions to one of 5,529 tools across 1,455 verified sources and returns an answer with stable citation URIs. It explicitly positions itself as the default entry point and preemptively distinguishes itself from sibling tools like ask_pipeworx_grounded and deep_research.

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

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

The description gives explicit when-to-use guidance: 'PREFER OVER WEB SEARCH' for factual questions, and 'START HERE for most questions'. It also names alternatives and the conditions for stepping up to ask_pipeworx_grounded or deep_research, plus a note on breaking-news routing.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses the beta/experimental status, that candidate routing improvements are enabled live only when under test, and that no candidate is active currently (so it matches ask_pipeworx exactly). It also clarifies that it has no fallback but is a full working router. No contradiction with annotations.

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

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

The description is four sentences, each adding essential context: beta status, current state (no candidate active), usage instruction, and reassurance that it's fully functional. There is no redundancy or fluff.

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

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

Covers the purpose, current behavior, relationship to the stable router, and response shape ('same response shape') despite lacking an output schema. It could be slightly more explicit about what 'candidate routing' might entail, but for an agent familiar with ask_pipeworx, it is largely complete.

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

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

The input schema already provides 100% coverage, documenting the 'question' parameter and its aliases. The description adds no extra parameter-specific meaning beyond referencing ask_pipeworx, so the baseline score of 3 is appropriate since the schema carries the load.

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

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

The description clearly identifies this as a beta version of ask_pipeworx, a universal router with the same 5,529 tools, arguments, and response shape. It distinguishes itself from the stable sibling ask_pipeworx by highlighting experimental routing improvements, making the purpose unambiguous.

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

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

Explicitly states 'Use it exactly like ask_pipeworx when you want the newest routing' and notes that results are compared against the stable router for merge decisions. This provides a clear when-to-use directive and implicitly names the stable router as the alternative for non-experimental use.

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

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

Annotations already set readOnlyHint=true, but the description adds crucial behavioral context: it 'EXTRACTS the answer using ONLY what the tool result contains,' explicitly lists refusal reasons, and explains the extra LLM call cost. It also clarifies the return structure (evidence, confidence, source). No contradictions with annotations; this goes far beyond what annotations provide.

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

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

Three sentences deliver the core purpose, routing mechanism, output format, refusal modes, usage guidance, and cost comparison. Every sentence earns its place with no filler. Front-loading the main behavior ('Hallucination-resistant answer mode') makes it immediately scannable.

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

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

With no output schema, the description fully explains the return value shape (answer, evidence, confidence, source, fetched_at) and refusal reasons. It also covers the trade-off versus ask_pipeworx and situational suitability. For a complex tool with one input parameter, this is remarkably complete—nothing critical is left to guess.

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

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

The input schema covers all parameters with 100% description coverage, including aliases. The description only says 'Your question in natural language' without adding syntax or format details beyond the schema. Baseline 3 is appropriate since the schema already handles 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 opens with 'Hallucination-resistant answer mode for high-stakes reads,' a specific verb+resource phrasing. It clearly states the tool's role: extracting answers using only tool result content, and distinguishes from sibling ask_pipeworx by noting the extra LLM call and stricter grounding. This makes the tool's purpose unambiguous and differentiates it from similar tools.

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

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

The description explicitly states when to use it: 'whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts,' and provides the alternative: 'prefer ask_pipeworx for casual lookups.' It also mentions the same routing as ask_pipeworx and the cost trade-off, giving clear 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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description details complex behaviors: low-confidence short-circuit, closed market handling, spread liquidity warnings, resolution-rule risk parsing, and fallback logic for news sources. This is far richer than annotations alone.

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

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

The description is long but well-structured with clear sections (classifiers, fan-out examples, response shapes, safety). It front-loads the core purpose. While every sentence adds value, some users might find the verbosity slightly high.

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 fully explains all possible response fields, error states (low-confidence, closed markets), edge cases (wide spreads, cancellation rules), and behavior under various conditions. It is remarkably complete for a complex tool.

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

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

Schema coverage is 100%. The description adds rich context beyond schema definitions: explains the 'depth' enum options and defaults, clarifies 'market' accepts multiple formats, and explains 'include_raw' usage and payload size implications.

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 statement: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies input types (slug, URL, question text) and explicitly lists use cases ('should I bet on X', 'what does the data say about Y', 'is there edge in Z'), distinguishing it from sibling tools like polymarket_edges.

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

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

The description provides explicit example queries and use cases, but does not directly compare to sibling alternatives or state when not to use this tool. It implicitly covers context by listing what the tool does, but lacks exclusionary guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about default full-series return (full_series=1), reliability, keyless access, and the opaque param's behavior. No contradictions.

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

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

Exceptionally concise: three focused sentences covering purpose, usage context, and param caution. Every sentence adds value without redundancy.

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

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

Given no output schema, the description fully explains the return format (time series with specific columns). Parameter descriptions are complete, and it references the sibling for ID lookup. The tool is self-contained and clear.

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

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

Schema coverage is 100%, and the description enriches each parameter: 'id' with examples, 'lang' with enum values, 'param' with detailed usage notes and constraints. Exceeds mere schema replication.

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 specifies a clear verb ('Fetch') and resource ('Hong Kong Census & Statistics Department statistical table'), details the output format (structured JSON with time series columns), and distinguishes itself from sibling 'censtatd_search_tables' by guiding users to find table IDs 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?

Provides explicit use cases ('HK GDP, employment earnings, trade, prices') and directs to sibling for ID discovery. Does not explicitly state when to avoid using this tool, but context is sufficient for most agents.

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 convey that the tool is read-only, open-world, idempotent, and non-destructive. The description adds valuable behavioral context: it searches an external index, coverage is incomplete, and it provides an alternative method to obtain IDs. This is useful beyond the annotations, though the annotations already handle the safety profile.

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

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

The description is extremely concise: two sentences with no unnecessary words. The first sentence delivers the core purpose and examples, the second adds important context (coverage limitation and alternative). Every part earns its place, and the structure is front-loaded for quick understanding.

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

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

Given the tool's simplicity (search with text query, returns IDs and titles), and no output schema, the description adequately sets expectations. It explains what the tool returns, its limitations (incomplete coverage), and how to find missing IDs. This is complete for an agent to decide when and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful context: it explains how to use the query parameter with examples ('exchange rates'), clarifies the limit parameter's default and maximum, and mentions the data source ('backed by the data.gov.hk open-data index'), which adds value beyond the schema.

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

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

The description clearly states the tool's purpose: searching the Hong Kong C&SD table catalogue by keyword to retrieve matching table IDs and titles for use with censtatd_get_table. It provides specific examples of keywords and distinguishes itself from sibling tools (censtatd_get_table, censtatd_table_info) by positioning this as the search step.

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

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

The description explicitly states when to use this tool (to search by keyword) and provides a when-not scenario: not every C&SD table is indexed, and offers an alternative method (reading IDs from the URL). It also explains the data source (data.gov.hk open-data index), giving agents clear context for decision-making.

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 confirms the tool is read-only ('without pulling the data') and non-destructive, aligning with all annotations (readOnlyHint, destructiveHint, idempotentHint). It adds specific behavioral details (returns title, notes, source) beyond the annotations, providing clarity on what the tool does without overpromising.

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

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

The description is two concise sentences with no redundancy. The first sentence packs core purpose, resource, and return values. The second provides a clear usage directive. Every word serves a purpose, 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 simple (2 params, no output schema), and the description covers all necessary aspects: purpose, return items, usage in a workflow, and implicit safety via annotations. It is fully complete for an agent to decide when and how to invoke this tool.

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

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

Schema coverage is 100% and the parameter descriptions in the schema are clear. The tool description does not add extra semantic depth beyond what the schema provides (e.g., it doesn't explain the format of 'id' or the values of 'lang'). Baseline score of 3 is appropriate as the description doesn't fall short but also doesn't elevate understanding further.

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

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

The description clearly states the verb 'Get', the resource 'metadata for a Hong Kong C&SD statistical table', and explicitly lists what is returned (title, footnote, source/contact). It distinguishes itself from the sibling tool 'censtatd_get_table' by saying 'without pulling the data', making the tool's specific role unambiguous.

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

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

The description explicitly advises using this tool to 'confirm a table id and read measurement caveats before calling censtatd_get_table', giving clear context and a sequential dependency. It implies not to use it when full data is needed. A slight improvement would be an explicit 'do not use' condition, but the guidance is already strong.

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, destructiveHint=false. The description adds detailed behavior: for company type, it pulls 'LATEST 10-K revenue + net income + cash + long-term debt from SEC EDGAR/XBRL' and handles off-calendar fiscal years; for drug type, it pulls 'FAERS adverse-event counts, FDA approval counts, active trial counts.' It also notes results are sorted by primary metric and returns 'paired data + pipeworx:// citation URIs per entity.' No contradiction.

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

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

The description is fairly long but every sentence adds value: natural language triggers, purpose, data sources, handling of special cases, sorting, and return format. It is front-loaded with common queries. Slight redundancy ('side-by-side comparison' repeated) but overall efficient.

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 complexity (two entity types, multiple data sources, sorting, citation URIs), the description covers purpose, parameters, behavior, and return format. There is no output schema, but the description explains what is returned: 'paired data + pipeworx:// citation URIs per entity.' It also mentions handling of off-calendar fiscal years, showing completeness.

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

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

Schema coverage is 100% and both parameters have descriptions and enums. The description adds context: explains type values ('company' or 'drug') with examples ('tickers/CIKs' for company, 'drug names' for drug), and clarifies that values must be 2-5 items. This enriches the schema but schema already does a solid job.

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

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

The description starts with natural language queries ('Compare X and Y', 'X vs Y') and clearly states it provides 'side-by-side comparison of 2-5 companies or drugs in ONE parallel call.' It explicitly distinguishes from siblings by preferring over sequential lookups. The verb 'compare' and resource 'entities' 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?

The description gives explicit usage scenarios: when user asks for comparison, ranking, or head-to-head. It advises to 'ALWAYS PREFER over sequential single-pack lookups,' implicitly excluding sequential lookups. It also states it replaces 8-15 sequential lookups, clearly defining its niche.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses latency (15-60s, up to 90s), account/pricing requirements, the findings packet structure, citation semantics, explicit gaps[] for unanswerable facets, and the fact that it never invents answers. It also details second-hop iteration behavior for different depth levels. No contradiction with annotations.

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

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

The description is dense and long, but every sentence earns its place—covering account requirements, alternatives, data sources, process, output format, limitations, and latency. It is front-loaded with critical account and alternative-tool information. Slightly run-on as a single paragraph, but the complexity justifies the length.

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

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

Given there is no output schema, the description fully explains the return packet: verbatim evidence, confidence, source, fetched_at, stable citations, gaps[], contradictions[], and hop field. It also covers limitations (structured data only, not open-web), timing, and depth semantics, making the tool fully operable 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%, but the description adds substantial meaning: it explains the depth parameter's three values (quick=3, standard=5, thorough=8) and their behavioral consequences (gap recovery, contradictions scan, iterative leads). It also clarifies that 'question' accepts broad/multi-part natural language, adding value beyond the schema's minimal descriptions.

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

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

The description clearly states the tool's purpose: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' in one call. It distinguishes itself from open-web search and names sibling tools like ask_pipeworx, with concrete examples of appropriate questions.

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

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

Provides explicit when-to-use guidance: 'Best for broad/multi-part questions over structured data' and when-not-to-use: 'For a single lookup use ask_pipeworx' and for breaking/current news prefer ask_pipeworx. Also specifies account prerequisites and alternative tools based on sign-in state.

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 behavior. Description adds that results include full schemas and are ready to call, no second lookup needed. No contradictions and provides useful output format 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?

Description is moderately long but efficient, front-loaded with core purpose, and uses domain examples effectively. Every sentence adds value, no 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 6 parameters, 1 required, and no output schema, description adequately explains output content and readiness for use. Provides enough context for an agent to understand what the tool returns and how to use it.

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

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

Schema coverage is 100% with all parameters described, including aliases and defaults. Description does not add parameter-specific semantics beyond listing example domains, but schema already suffices. 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 'Find tools by describing the data or task' and lists specific domains, distinguishing it from sibling tools by emphasizing discovery and returning ready-to-call results with full schemas.

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 advises 'Call this FIRST when you have many tools available and want to see the option set,' providing context for when to use it. Does not explicitly mention when not to use alternatives, but scope is 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 establish read-only, idempotent, and non-destructive behavior. The description adds significant behavioral detail: fans out across multiple sources, returns specific fields (CIK, filings with URIs, fundamentals sorted, patents with sunset note, news fallback, LEI), and explains the patents API sunset. This exceeds what annotations alone 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 about 150 words but front-loaded with example queries, and each sentence provides useful information. It is information-dense and earns its length, though a more structured layout (e.g., bullet points) could improve readability.

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

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

Given the complexity of the tool (multiple data sources, no output schema), the description thoroughly explains what data is returned, how sources are used, and constraints. The lack of an output schema is mitigated by the detailed return field enumeration. It is sufficiently complete for the 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 description coverage is 100% with both parameters described. However, the description adds crucial context beyond the schema, such as emphasizing that names are not supported and recommending resolve_entity, and providing example formats (ticker 'AAPL' or zero-padded CIK).

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 clear, user-intent example queries ('Tell me about X', 'research Acme') and explicitly states it provides a 'full cross-source profile of a US public company'. It distinguishes itself from siblings by advising 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view'.

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 includes explicit guidance: 'ALWAYS PREFER over chaining...', notes that names are not supported and to 'use resolve_entity first', and mentions that patents soft-fails. This provides clear when-to-use and when-not-to-use instructions.

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 destructiveHint=true and idempotentHint=true. The description confirms deletion without contradicting annotations. However, it does not disclose additional behaviors like error handling for missing keys, which would be helpful.

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

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

Two sentences: first states purpose, second gives usage conditions. No unnecessary words. Well-structured and front-loaded.

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

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

For a simple tool with one parameter and no output schema, the description covers all essential aspects: purpose, when to use, and parameter meaning. No gaps.

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

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

Schema coverage is 100% and the description 'Memory key to delete' closely mirrors the schema description. No additional semantic value beyond what schema provides.

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

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

Clearly states the action (Delete) and resource (previously stored memory by key). Distinguishes from sibling tools like 'remember' and 'recall' by mentioning them in context.

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 tells when to use: stale context, task done, or clearing sensitive data. Also suggests pairing with related tools, providing clear 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, openWorldHint, idempotentHint, and non-destructive behavior. The description adds process details (fetching, extracting, emitting markdown) without contradicting annotations. It effectively complements the structured data.

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

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

The description is two sentences, front-loading the purpose and following with a useful list of use cases. It is efficient and avoids redundancy, though the second sentence could be slightly more compact.

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 2 parameters and no output schema, the description adequately explains the output format (single text blob) and destination (site-root/llms.txt), providing sufficient context for an agent to use it correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing default and max values for max_links (default 25, max 50) and an example URL format, enhancing understanding beyond the schema.

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

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

The description uses specific verbs ('generate', 'fetches', 'extracts', 'emits') and clearly identifies the resource (llms.txt file). It distinguishes itself from sibling tools by focusing on a unique action (generating llms.txt for AI crawlers) not covered by others like search or research tools.

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

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

The description explicitly lists use cases: getting a client's site indexed, drafting for own project, auditing a competitor. It provides clear context for when to use, though it does not explicitly state when not to use or mention alternatives among siblings.

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

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

Annotations already supply readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description goes beyond these by disclosing the critical behavioral nuance that figures are 3-MONTH MOVING AVERAGES, explaining that '2026-06' means April–June, and noting the keyless/`source` character of the data. This is valuable behavioral context annotations cannot 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 dense but efficient — roughly three sentences covering purpose, example queries, data source, and the moving-average caveat, all front-loaded with the core purpose. Every sentence earns its place, and the use of CAPS emphasis ('ONE call', '3-MONTH MOVING AVERAGES', 'PREFER') draws attention to the most important distinctions.

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 a single optional parameter, no output schema, and rich annotations, the description covers everything an agent needs: what data is returned, the interpretation caveat (moving averages), the source, and the boundary against a sibling tool. There is no ambiguity left about invocation or result interpretation.

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 single `months` parameter is fully documented in the schema (range 1-120, default 12). The description adds a modest but useful note that 'The headline fields always describe the newest', which clarifies the relationship between the series and the main headline outputs. This complements, rather than repeats, the schema definition.

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

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

The description states a specific verb+resource ('Hong Kong's headline labour-market figures in ONE call') and enumerates exactly which metrics are returned (unemployment rate SA and NSA, underemployment, labour-force participation). It also names the data source (Census & Statistics Department table 210-06101), distinguishing it clearly from sibling tools like censtatd_get_table and censtatd_table_info.

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

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

The description provides explicit when-to-use triggers with natural-language examples ('PREFER for "what is Hong Kong's unemployment rate"', 'HK jobless rate') and provides an explicit alternative: 'Use censtatd_get_table for anything deeper (by age, sex, industry)'. This clearly delineates this tool's scope from a deep-dive sibling.

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. Description adds that it returns specific fields and applies only to the caller's subscriptions, complementing annotations well.

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 efficient sentences: one for purpose/output, one for usage guidance. 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?

Fully covers what agent needs: purpose, returned fields, usage context, and parameter effect. No gaps given simplicity and rich annotations.

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

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

Schema has 100% coverage, including description for 'include_inactive'. The description does not add parameter details beyond schema, baseline 3.

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

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

Clearly states 'List the caller's active subscriptions' with specific verb and resource, and distinguishes from sibling tools like subscribe or unsubscribe.

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

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

Explicitly advises when to use: 'review what you're monitoring before adding more or to find an id to cancel', providing clear context and alternatives.

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

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

Annotations only set all hints to false, so the description carries the burden. It discloses rate limiting (5 per identifier per day), that it's free and doesn't count against quota, the daily digest review, and the claim_token mechanism. This goes well beyond the structured data.

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 detailed but every sentence serves a purpose. It is front-loaded with the core purpose, then systematically covers scope, usage, token mechanics, and rate limits. 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 tool with 4 parameters, no output schema, and nested objects, the description explains the full workflow: filing, receiving a token, checking resolution later, and the policy constraints. It adequately covers all necessary operational context.

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

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

Schema coverage is 100%, so the schema already documents parameters thoroughly. The description adds general guidance (e.g., describe issues in Pipeworx terms, don't paste user prompts) but doesn't significantly expand on individual parameter meanings beyond what the schema provides.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the tool as a feedback channel. It enumerates the specific feedback types (bug, feature, data_gap, praise) and differentiates from sibling research/query 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?

Provides explicit when-to-use triggers ('Use when a tool returns wrong/stale data...') and a clear exclusion ('if the tool came from a different MCP server... file it with that server instead'). Also instructs not to paste end-user prompts, and explains the claim_token workflow for follow-up.

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, non-destructive. The description adds valuable context: data is self-aggregating, derived from CF analytics-engine, no PII, and cached 5min-1h. No contradiction with annotations.

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

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

The description is front-loaded with the key purpose and uses numbered use cases for structure. It is informative without being verbose, though slightly longer than minimal.

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 only one optional parameter and no output schema, the description fully covers what the tool does, why to use it, and its caching behavior. No gaps remain for agent decision-making.

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

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

Schema coverage is 100% with one enum parameter. The description explains the window options ('24h, 7d, 30d') and their behavioral difference (hot vs steady-state demand), adding meaning beyond the schema's description.

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

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

The description clearly states the tool returns top tools, top packs, and call volume over a window. It uses specific verbs ('returns') and resources ('tools, packs, call volume'), distinguishing it from siblings like ask_pipeworx or discover_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?

Three explicit use cases are listed (discovering hot data, confirming canonical tools, aligning with agent needs). While it doesn't name alternative tools for different contexts, the guidance is clear and actionable.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint), the description adds rich behavioral details: semantic anchor with Jaccard similarity threshold, partition filter for placeholder slugs, fill check against live CLOB depth, and trade suggestion conditions. This fully covers what the tool does and its limitations.

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

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

The description is front-loaded with the main purpose but becomes verbose, including technical details like '≥0.30 Jaccard similarity' and multiple signal types. While informative, it could be more concise by moving some details to the schema or output 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?

Given the complexity (multiple modes, no output schema), the description is thorough. It outlines the response structure (opportunities[], partition_check), fill check logic, and mentions related tools (polymarket_fill_risk). Covers edge cases like skipped_low_similarity and placeholder filters.

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

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

Schema description coverage is 100%, with both parameters already described. The tool description adds value by explaining accepted formats (e.g., full Polymarket URLs for event, seed questions for topic) and the mode selection logic, going beyond the schema alone.

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

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

The description clearly states the tool's purpose: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' It specifies the verb (find), resource (arbitrage opportunities on Polymarket), and method, distinguishing it from sibling tools like polymarket_fill_risk and polymarket_edges.

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

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

The description explains two modes (event and topic) with recommendations (e.g., 'event (recommended for a specific market)'). It provides context on when to use each and mentions polymarket_fill_risk for custom sizing. However, it lacks explicit exclusions or when not to use this tool.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint true and destructiveHint false. The description goes far beyond by detailing caching (1h KV level), the specific models and their formulas (lognormal barrier, GDELT volume ratio, partition_overround with per-sport α, placeholder-slug filter), edge components (edge_pp_net, kelly_fraction, kelly_fraction_half capped at 0.25, 24h-move warning), and tradeable-edge filters. 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 very long (multiple paragraphs with technical details) but is front-loaded with the core purpose and structured by segments (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT). While every sentence adds value, it could be more concise for quick reading. It earns a 3 because it is dense and slightly overwhelming, though well-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?

Despite lacking an output schema, the description explains the response structure in detail (by_segment with three categories, fed_candidates/fed_note with caveats, _diagnostics with funnel counters). It also covers caching behavior, edge calculation details, and the meaning of each parameter in context. For a complex tool with 9 parameters and numerous output fields, this is remarkably complete.

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

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

Schema coverage is 100% and each parameter already has a description. The tool description adds context: for example, explaining why min_kelly defaults to 0 ('Skips opportunities that are too small'), why max_spread_pp should be set to 2 ('tight books'), and why min_liquidity should be 5000 ('drop thin-book opportunities where executing the edge would walk the book past breakeven'). This enriches understanding beyond the schema.

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

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

The description clearly states the tool scans Polymarket markets and returns opportunities where Pipeworx data disagrees with market price. It lists three specific model families (MODEL_DRIVEN, STRUCTURAL_ARBITRAGE, CONCENTRATED_LONGSHOT), distinguishing it from sibling tools like polymarket_arbitrage, polymarket_edge_tracker, etc.

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

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

The description explicitly states the tool is 'Built for "what should I bet on today"' and that agents discover opportunities without paging. It explains the 'tradeable-edge knobs' (min_liquidity, max_spread_pp, min_partition_leg_kelly). However, it does not explicitly mention when not to use it or compare to specific siblings, which would earn a 5.

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

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

Beyond annotations (read-only, idempotent, etc.), the description discloses critical behavioral details: data sourced from daily snapshots with possible cache-miss gaps, decay computed from daily closes (not intraday), 60-day snapshot TTL limit, and detailed response structure. 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 well-structured, starting with purpose, then a use-case, parameters, and detailed response format. It is informative but somewhat lengthy; however, given the lack of output schema, the detail is justified. Could be slightly more concise.

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

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

Despite no output schema, the description fully explains the return format (tracked, expired, snapshot_dates) with key fields. It covers limits, edge cases (data gaps), and decay calculation basis. Extremely complete for the tool's complexity.

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

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

Schema coverage is 100% with both parameters fully described in the schema. The description repeats defaults and enumerations but adds minimal additional semantic value, such as clarifying 'window' as snapshot family. Baseline score of 3 is appropriate.

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

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

Description clearly states the tool provides 'edge persistence and decay telemetry' using daily snapshots, answering how long an edge has existed and if it is shrinking. It distinguishes itself from sibling 'polymarket_edges' by focusing on historical time-series and trend analysis rather than current edges.

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

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

The description gives a concrete use case comparing fresh versus old edges, indicating when to use this tool for historical perspective. However, it does not explicitly contrast with siblings like polymarket_edges or suggest when not to use this tool.

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

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

Annotations already indicate readOnly, openWorld, idempotent, nondestructive. Description adds valuable behavioral context like walking the ladder, returning verdicts (clean/degraded/cannot_fill), forced directional risk, and thin_legs, enhancing 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?

Well-structured with clear sections for single-market and basket modes. Dense but every sentence adds value, no fluff. Front-loads key purpose and required parameters.

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

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

No output schema, but description comprehensively lists returned fields for both modes (top_of_book, vwap_fill_price, capture_ratio, profit_usd, thin_legs, etc.) and explains forced directional risk. Fully covers what agent needs to know.

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%. Description adds meaning beyond schema by explaining side defaults for basket mode (auto from partition sum), size_usd interpretation (max spend vs target proceeds for singles, settlement notional for basket), and parameters format (slug/URL).

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 a 'realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes single-market from basket modes with specific return fields for each.

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

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

Explicitly instructs to use this tool before acting on polymarket_arbitrage signals or trades above ~$500, and explains risks of partial fills and uncapturable overround, providing clear when-to-use guidance.

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

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

The description adds significant behavioral context beyond annotations: it explains compatibility warnings, temporal alignment, skipped cross types (metric_type mismatch, inequality mismatch). It states when spreads are meaningful vs. meaningless (temporal misalignment). No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint).

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

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

The description is detailed and front-loaded with purpose, modes, response fields, and safety explanation. Every sentence adds value given the tool's complexity. However, it is slightly verbose; a more streamlined structure could improve readability without losing information.

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

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

The description explains response fields (leg-by-leg prices, spread values, compatibility_warning, temporal_alignment, skipped counters) in the absence of an output schema. It covers edge cases (compatibility warning scenarios, temporal misalignment). All three parameters are documented with usage details and examples.

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

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

Schema coverage is 100% with all parameters described in schema, but the description adds substantial meaning: details on topic shortcuts (10 macros), overriding behavior for explicit tickers, and examples (e.g., KXFED-26OCT, fed-decision-in-june-825). This fully compensates for any schema 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 calculates the cross-venue spread between Kalshi and Polymarket for the same resolving question. It distinguishes from sibling tools like polymarket_arbitrage by focusing on cross-venue comparison. Two modes are described (topic shortcuts and explicit tickers), providing specific verb-resource identification.

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

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

The description explicitly explains when to use each mode: topic for quick macro lookups, explicit tickers for custom pairings. It warns that most pre-mapped topics return compatibility warnings and are not tradeable. Safety fields like compatibility_warning provide clear when-not guidance, including scenarios where no arb exists or events are semantically unrelated.

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, destructiveHint. Description adds scoping detail (per user identifier) and pairing info, going beyond annotations.

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

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

Three sentences, front-loaded with primary action, no redundant words. Efficient and clear.

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

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

Covers purpose, usage, scoping, and pairing with related tools. Single optional parameter and no output schema are acceptable given the tool's simplicity and annotation 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?

Input schema has 100% description coverage, already explaining the 'key' parameter. Description restates same meaning without adding additional detail beyond what schema provides.

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

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

Clearly states the tool retrieves a saved value or lists all keys, using specific verb ('Retrieve', 'list') and resource ('value', 'keys'). Distinguishes from siblings '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?

Provides context for when to use (look up stored context to avoid re-deriving) and pairs with remember/forget. Does not explicitly state when not to use or compare to other sibling tools.

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

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

Annotations already mark readOnlyHint=true, etc., and the description adds value by explaining the mark_read flag, filtering behavior, and that the feed is the same as a REST endpoint. 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?

Four sentences, each serving a purpose. The core action is stated first, followed by return details, parameter hints, and usage guidance. No unnecessary 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?

The description covers return payload components, filtering options, mark_read behavior, and an alternative access method. For a read-only tool with 5 optional parameters and strong annotations, this is 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?

With 100% schema coverage, baseline is 3. The description adds examples for type (e.g., 'sec_8k'), clarifies ISO timestamp format for since, and explains mark_read side effects, thus providing additional 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 states the tool's verb and resource: 'Pull fired events from your subscription feed' and specifies that it returns the most recent alerts with key fields. This distinguishes it from other sibling tools that deal with different data or actions.

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 advises that 'Polls work fine' and points to an alternative REST endpoint for scripts and dashboards. It provides context on when to use polling, but does not explicitly state when not to use this tool versus other 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?

The description goes well beyond the annotations (which already indicate safe read operation) by detailing the multi-source fan-out (SEC EDGAR, GDELT/GNews, USPTO), fallback behavior, soft-fail for USPTO, parameter format details, and return structure. No contradictions with annotations.

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

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

The description is a dense paragraph but every sentence adds value. It could be slightly more structured (e.g., with bullet points for sources), but it remains reasonably concise and front-loaded with usage 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?

Given no output schema, the description provides a good overview of return structure (changes grouped by source, total_changes count, citation URIs). For a tool with 3 parameters and rich annotations, it covers functional behavior, sources, fallback, and sibling differentiation, missing only detailed output field explanations.

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

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

With 100% schema description coverage, the description still adds significant value: it explains accepted formats for 'since' (ISO vs relative), suggests typical values ('30d', '1m'), and details that 'value' can be ticker or CIK. This meaningfully supplements the schema.

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

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

The description clearly states the tool's purpose: a change feed for a company in a time window. It provides multiple example queries ('What's new with X', 'latest on Y') and explicitly distinguishes from sibling tool entity_profile, which handles static profiles. This makes the purpose highly specific and differentiated.

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

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

The description gives clear guidance on when to use this tool versus entity_profile, and explains the fallback logic from GDELT to GNews. However, it does not explicitly list scenarios where this tool should not be used, though the sibling distinction implies it.

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?

Discloses persistence behavior (authenticated users persistent, anonymous 24h) and scoping. Annotations already indicate idempotent and non-destructive, but description adds meaningful session-level details.

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

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

Three sentences, front-loaded with purpose, no redundant information. Every sentence adds value.

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

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

Given no output schema, description sufficiently explains storage behavior, scope, and pairing with recall/forget. Parameter count is low and fully covered.

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

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

Schema covers both parameters fully; description adds value with example key formats and clarifies value can be any text, aiding agent understanding beyond 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 saves data for later reuse, specifying key-value pairs scoped by identifier. It distinguishes from sibling tools recall and forget by explicitly mentioning pairing.

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 clear usage context: store discovered information like tickers, addresses, preferences. Does not explicitly state when not to use, but the context and pairing with recall/forget imply 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, open-world, idempotent, and non-destructive. The description adds substantial behavioral detail beyond these: it labels every identifier with its source, explicitly states that unresolved identifiers are included under 'unresolved' rather than omitted, and describes graceful degradation (LEI/FIGI enrichment fails but EDGAR IDs still return). It also discloses that each call cascades through multiple internal endpoints, which is useful for setting expectations.

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, starting with concrete examples and a clear 'Use FIRST' directive, then breaking down supported types with parentheses for details. Every sentence adds value (examples, supported types, degradation, source labeling). It could be slightly more scannable with bullet points, but it is appropriately sized for the complexity of the tool.

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

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

Given the tool has no output schema, the description thoroughly explains what is returned for each type: for company, lists CIK, ticker, company_name from SEC EDGAR, LEI from GLEIF with ownership info, FIGI from OpenFIGI, plus unresolved handling; for drug, lists RxCUI, ingredient, brand, and citation. It also covers failure modes (graceful degradation) and the multi-endpoint cascade, making the behavior complete and 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?

The schema already covers the parameters 100% with descriptions for 'type' and 'value'. The description goes far beyond by elaborating the accepted input formats for 'value' (ticker, CIK, company_name for companies; brand/generic names for drugs) and detailing the output components that each type will produce. This adds significant context for constructing correct calls, especially for the enumerated 'type' parameter.

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

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

The description clearly states the tool's purpose: resolving user-spoken names to canonical/official identifiers required by other tools. It provides concrete example queries ('What's the ticker for…', 'find the CIK for…'), explicitly names the output types (CIK, ticker, LEI, FIGI, RxCUI), and distinguishes itself from siblings by saying 'Use FIRST whenever you have a name but need an ID.' This is specific and unambiguous.

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

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

The description gives a clear directive: 'Use FIRST whenever you have a name but need an ID.' It also explains that the tool replaces 2-3 manual lookups and handles graceful degradation, which helps the agent decide when to use it. However, it does not explicitly list when not to use it (e.g., when an ID is already known) or name alternative sibling tools, though the context makes this reasonably inferable.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds that the tool probes each entity with 'ai_visibility_check', ranks by score, and surfaces most/least recognized. This enriches behavioral context beyond annotations.

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

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

The description is four sentences, dense with information, and front-loads the core purpose. Every sentence earns its place without redundancy.

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

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

Given the tool's complexity (ranking multiple entities) and absence of an output schema, the description covers purpose, usage, and return fields (score, confidence, signal density). This is sufficient though slightly abstract about the ranking algorithm.

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

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

Schema coverage is 100% so baseline is 3. The description adds value by explaining that 'entities' array's first entry is treated as the subject and rest as competitors, which is not clear from the schema alone.

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

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

The description uses specific verbs ('compare', 'probes', 'ranks', 'surfaces') and clearly identifies the resource ('AI visibility across multiple entities'). It distinguishes itself from the sibling 'ai_visibility_check' by emphasizing multi-entity side-by-side comparison and ranking.

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

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

The description explicitly states usefulness for 'competitive AI-marketing audits' and gives a concrete example question. It implies single-entity checks should use 'ai_visibility_check', but does not explicitly list when not to use or mention all 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 idempotent, read-only, and non-destructive behavior. The description adds critical behavioral context about bundlephobia's first measurement taking 5–30 seconds and sources_failed being listed on timeout. 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?

Description is lengthy but every sentence adds meaningful information. It is front-loaded with the core purpose and structured logically. Could be slightly more concise but not wasteful.

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

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

Given the tool's complexity (multi-source check, partial failures) and no output schema, the description covers the return format (summary block with fields, per-advisory detail, links, alternative versions) and edge cases. Additional minor details like what 'links' contain could be specified, but it's very complete.

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

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

Schema coverage is 100% with clear descriptions. The description adds value by explicitly accepting scoped packages and clarifying version defaulting to latest, going slightly beyond schema detail.

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

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

The description clearly states the tool's purpose as a composite check for deciding whether to add an npm package, covering license, advisories, version history, and bundle size. It distinguishes itself from sibling tools by explicitly limiting to NPM ecosystem in v1.

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 ('whenever an agent asks "is X safe / popular / small"') and when-not-to-use ('NPM ecosystem only in v1; PyPI / Maven / Cargo / Go fall under deps.dev:version directly'), plus mentions graceful partial failure handling.

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

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

Annotations already provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false. Description adds technical details: BGE-base-en embeddings, cosine similarity, 500-char windows, 200K char cap with truncation flagging, and return of offsets and scores.

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

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

Every sentence is informative and earns its place. Front-loaded with purpose, then usage, technical details, and pairing information. No redundancy.

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

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

Given the tool's complexity, annotations cover safety, schema covers parameters, and description adds model details, constraints, and return format. No gaps for an agent to misuse the tool.

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

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

Schema description coverage is 100%, so baseline is 3. Description does not add new semantic information beyond the schema for the parameters; it only provides usage examples (e.g., query examples) which are helpful but not essential.

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 'Semantic search INSIDE a fetched record' with specific verb and resource. It distinguishes from sibling 'ask_pipeworx_grounded' by explaining how they pair together.

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

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

Explicitly says 'Use when the record is too big to cram into the prompt' and provides alternative pairing with ask_pipeworx_grounded, giving clear when-to-use and when-not-to-use guidance.

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

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

Adds substantial behavioral context beyond annotations: explains OAuth requirement, return of subscription ID, delivery channel details, SMS cap, and webhook failure handling. The idempotentHint annotation is not fully addressed (description implies each call creates a new subscription), but overall transparency is strong.

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?

Description is efficiently structured with purpose front-loaded, followed by requirements, types, and delivery details. No redundant sentences, but could be slightly tighter.

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

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

Covers all aspects: types, parameters, delivery options, authentication requirements, and limitations. Without an output schema, it adequately describes return value (subscription ID) and behaviors.

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 enriches parameters with examples for each type's params (e.g., 'sec_8k: {ticker:"AAPL", items?:["5.02"]}'}) and detailed delivery channel semantics beyond the schema's basic descriptions.

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

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

The description clearly states 'Create a proactive monitoring subscription to a live-data event stream' using a specific verb ('Create') and resource ('subscription'). It distinguishes from sibling tools like 'list_subscriptions' and 'unsubscribe' by focusing on creation.

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 context: requires Pipeworx OAuth account, lists supported types with examples, and details delivery channels with limitations (e.g., SMS 10/day cap, webhook auto-disable). Does not explicitly state when not to use, but overall guidance is 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 provide readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds value by explaining the return structure (category-bucketed example questions with tool shapes) and call behavior (no args for full spread, topic to focus). No contradiction. Could mention idempotency but not required.

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: starts with common questions, then describes output and usage. It is informative without being verbose, though slightly longer than minimal. Every sentence adds value.

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

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

For an onboarding tool with no output schema, the description fully explains what the tool returns (category-bucketed examples with tool shapes), how to invoke it, and its role. It is complete given the tool's simplicity and the annotations provided.

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 one optional parameter described. Description adds context: examples of valid topic values and the effect of omitting vs. providing a topic. This goes beyond the schema's minimal 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 uses specific verbs and resources: 'onboarding entry point' that 'returns category-bucketed example questions' with exact tool and argument shape. It clearly distinguishes from siblings like ask_pipeworx and discover_tools by stating it answers 'what can you do?' and provides examples.

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

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

Explicitly states when to use: 'first when you do not yet know what Pipeworx can do for you, or to learn how to call the meta-tools'. Also covers optional topic filtering. No explicit when-not-to-use or alternatives, but context 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 indicate non-read-only, idempotent, and non-destructive behavior. The description adds valuable details: ownership enforcement (security behavior), deactivation vs. deletion (graceful state change), and preservation of historical events. 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?

Three concise, front-loaded sentences. The first sentence states the core action, the second addresses ownership, and the third explains the behavioral nuance. No redundancy or extraneous information.

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

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

Given the single parameter with full schema coverage and no output schema, the description sufficiently covers the tool's behavior and side effects. The information about ownership and deactivation makes it complete for an agent to use correctly.

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

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

With 100% schema coverage, the baseline is 3. The description adds context by referencing 'id' as the subscription id returned by 'subscribe', reinforcing the parameter's origin and 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 states the action ('Cancel a subscription by id') and the resource ('subscription'). It distinguishes from sibling tools like 'subscribe' and 'list_subscriptions' by explaining ownership enforcement and the deactivation mechanism, making the tool's purpose unambiguous.

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

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

The description provides explicit context for when to use the tool — to cancel your own subscriptions. It does not explicitly list when not to use it or alternatives, but the ownership rule and the note about historical events via 'recent_alerts' give clear usage boundaries.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds critical behavioral context: the distinction between 'could_not_verify' (verification_error, not evidence) and 'unsupported' (no source found), the return format with verdicts and citations, and the automatic fallback routing. This goes well beyond the annotations and is essential for safe agent use.

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

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

Although the description is longer than average, every sentence earns its place: trigger phrases, usage, routing, output semantics, and critical caller warnings. It is front-loaded with the tool's purpose and structurally organized, making it easy to parse. No filler or redundancy.

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

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

Given the tool's complexity, lack of output schema, and only two parameters, the description is exceptionally complete. It explains the verdict set, the difference between failure modes, the citation mechanism, and the fallback routing. This provides everything a caller needs to understand the tool's behavior without seeing the output schema.

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

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

Schema coverage is 100%, but the description enriches parameter meaning by explaining how tolerance_pct overrides the claim's implied tolerance and recommending 1-2% for hallucination detection. It also clarifies the default cap of 5%. This adds operational guidance not present in the schema alone, so a score above the baseline is warranted.

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 clear trigger phrases ('Is it true that…', 'fact check') and states the tool performs natural-language claim verification against authoritative sources. It explicitly distinguishes itself by describing the two routes (SEC EDGAR for company-financial claims vs. grounded pipeline for any other) and notes it replaces 4-6 sequential calls, clearly separating it from sibling tools like ask_pipeworx_grounded or deep_research.

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

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

The description gives an explicit usage directive: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also explains the routing behavior and the efficiency benefit. However, it does not explicitly state when not to use the tool or name alternative tools for different scenarios, so it falls just short of a 5.

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