Fcc Ecfs

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

Annotations declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint as false. The description adds that the default model is free, Anthropic requires a BYO key, and details the return format (per-model {score, confidence, signals, raw_response} plus combined view), fully disclosing behavior beyond annotations.

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

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

The description is two sentences, with the core action and return format in the first sentence and additional details in the second. It is well-structured and front-loaded, though the first sentence is slightly long. It avoids 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?

Given the tool has 4 parameters, no output schema, and comprehensive annotations, the description provides complete guidance: explains return format, model choices, cost implications, and example usage. It is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by providing concrete examples for 'entity' (e.g., 'Pipeworx', 'OpenInvoice'), explaining that 'models' can be omitted for just workers-ai, that '_apiKey' is passed directly to Anthropic, and that 'context' helps disambiguate names. This enriches parameter understanding.

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

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

The description explicitly states the tool probes LLMs for knowledge about entities and scores visibility (0-100) per model, with specific examples. It clearly distinguishes from sibling tools by focusing on AI visibility scoring for marketing audits, brand checks, and competitive monitoring.

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

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

The description provides clear usage scenarios like AI-marketing audits and pre-launch brand checks, and explains when to use different models (free default vs. paid Anthropic). However, it does not explicitly exclude alternative sibling tools or provide conditions 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 mark the tool read-only, open-world, idempotent, and non-destructive. The description adds useful behavioral context: it routes to one of 5,767 tools, fills arguments, returns structured answers with stable citation URIs, and routes news queries to live news feeds. It does not contradict annotations and supplements them with meaningful detail.

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 critical preference and function, then provides trigger phrases, examples, and sibling routing. It is slightly repetitive ('even if web search could also answer it' appears twice) and places 'START HERE' guidance after a long example list, but overall it is organized and every section earns its place.

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

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

For an orchestrator-like tool with no output schema, this description covers what the tool does, when to prefer it, sample questions, output shape (structured answer with citation URIs), and explicit alternatives for narrower or broader use cases. An agent has everything needed to select and invoke it correctly.

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

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

Input schema coverage is 100%, and the schema already documents 'question' plus aliases (q, text, input, query, prompt). The description reinforces natural-language usage with examples and trigger phrases, but adds little parameter-level meaning beyond what the schema already provides.

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

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

States a specific action—routes a natural-language question to the appropriate source tool, fills arguments, and returns a structured answer with citation URIs. It names the tool's resource class (5,767 tools, 1,506 verified sources), lists domains, and explicitly differentiates itself from siblings 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?

Explicitly says to prefer this tool over web search, enumerates trigger phrases ('what is', 'look up', 'find', 'get the latest', 'how much', 'current'), gives concrete examples, and directs to ask_pipeworx_grounded for verbatim single-slot answers and deep_research for broad/multi-part questions. This is 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?

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds crucial beta context: candidate routing improvements can be enabled live, none is currently active, and the tool is a full working router with no fallback. This is substantive behavioral disclosure beyond the annotations.

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

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

The description front-loads the beta identity and core function, then gives current state and usage. Some details, like the retirement date, are informative but could be trimmed. Overall it is structured and avoids padding, earning a 4.

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 high complexity of a universal router with no output schema, the description covers beta status, current equivalence, experimental live behavior, usage, and the fact that it is a full router. It references the same response shape as ask_pipeworx rather than describing it, leaving an agent to consult the sibling for exact return details. This is a minor gap, so 4.

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

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

The input schema documents all parameters and aliases with 100% coverage, so the description need not repeat them. The description only repeats that arguments match ask_pipeworx, which adds no per-parameter semantics. Baseline 3 is appropriate because the schema carries the semantic 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 identifies the tool as a beta version of ask_pipeworx and defines it as a universal router with the same 5,767 tools, arguments, and response shape. It clearly distinguishes this from the stable sibling by framing it as the experimental routing edge. The purpose is specific and not a tautology.

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

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

It explicitly says to use it exactly like ask_pipeworx when the agent wants the newest routing, and notes results are compared against the stable router to decide merges. The current no-candidate state is disclosed so the agent knows behavior matches the stable version today. It stops short of an explicit 'use ask_pipeworx for stable/production' exclusion, so it is not a 5.

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

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

Beyond the annotations, the description discloses the extraction-only behavior, the exact refusal reasons, the extra LLM call cost, and the structured return shape. This gives the agent a precise model of how the tool behaves on failure and success.

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

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

The description is dense but front-loaded: purpose first, then behavior, return format, and usage guidance. A few details (exact tool counts) are less essential, but they do not significantly dilute the message.

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

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

For a tool with no output schema, the description explains both success and refusal return shapes, specifies use cases, names the cheaper alternative, and covers failure modes. An agent has everything needed to call and interpret the result.

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%: every parameter (question plus aliases) is already documented in the input schema, so the description does not need to add more. It does not go beyond the schema, but the baseline of 3 applies because the schema carries the full burden.

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 concrete purpose: 'Hallucination-resistant answer mode for high-stakes reads' and specifies it extracts answers 'using ONLY what the tool result contains.' It also distinguishes itself from ask_pipeworx, so an agent can tell them apart.

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

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

It explicitly states when to use this tool ('whenever an answer will be quoted, cited, or acted on') and when not to ('prefer ask_pipeworx for casual lookups'). This is direct, actionable guidance with no ambiguity.

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

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

The description goes far beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It details the resolver contract (match confidence, alternatives), parent event extractor, news fields with fallback behavior, safety mechanisms (low-confidence match, closed markets, wide spread), and resolution-rule risk including real-world pitfalls. No contradiction with annotations. This is highly transparent and helps the agent understand edge cases.

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

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

The description is long but well-structured with sections (classifiers, fan-out examples, response shapes, etc.) that serve the tool's complexity. It is front-loaded with the main purpose. However, some parts are verbose (e.g., detailed fan-out examples could be streamlined). Every sentence earns its place, but a bit of trimming would improve conciseness.

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

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

Despite lacking an output schema, the description thoroughly covers the response shape (result.market, result.analysis, result.evidence), resolver behavior, parent event extraction, news fallback, safety checks, and resolution-rule risk. Given the tool's complexity (3 parameters, no output schema), this description is remarkably complete and leaves no major gaps in understanding.

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

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

The input schema has 3 parameters with 100% description coverage. The description adds substantial meaning: for 'market' it explains three accepted formats (slug, URL, question text); for 'depth' it clarifies 'quick = 2-3 evidence sources, thorough = full fan-out' with a default; for 'include_raw' it explains when to use true/false and the impact on response size. This enriches the structured schema significantly.

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

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

The description clearly states the tool's purpose: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It specifies the verb (Research), resource (Polymarket bet), and provides specific input examples (slug, URL, question text). While the purpose is very clear, it does not explicitly distinguish this tool from siblings like ask_pipeworx or deep_research, though the focus on Polymarket bets is differentiating.

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 use cases: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also gives examples of input types. However, it lacks guidance on when not to use this tool or alternatives among the sibling tools (e.g., validate_claim, deep_research). The context is clear but no exclusions or alternatives are mentioned.

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

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

Beyond annotations (readOnly, openWorld, idempotent, non-destructive), description adds specific data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, and sorting by primary metric. 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 thorough but efficient, front-loaded with examples. Every sentence adds value; some minor repetition could be trimmed, but overall well-structured.

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

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

Given the tool's complexity (2 entity types, multiple data sources, sorting, citation URIs), the description is complete. No output schema exists, but return format is described adequately. Covers when to use and replaces many sequential lookups.

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 covers both parameters with descriptions. The description adds semantic meaning: type='company' pulls specific financials, type='drug' pulls adverse-event counts, trial counts, etc., enriching the schema's enum descriptions.

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, with specific examples of natural language queries. It distinguishes itself from siblings like entity_profile by explicitly noting it replaces sequential lookups.

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

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

Provides explicit guidance: 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.' Gives example input patterns and explains behavior for each type.

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

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

Annotations already declare readOnlyHint/openWorldHint/idempotentHint, but the description adds substantial behavioral context beyond them: authentication and paid-tier requirements, parallel facet decomposition, expected latency, gaps[] for unanswered facets, contradiction[] output, citation_uri fetchability, and semantic excerpting. It also warns that results for non-catalog current-news topics are mostly empty gaps[]. No annotation contradiction exists.

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

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

The description is long but densely informative, front-loading the account requirement, core function, and routing guidance before diving into depth mechanics and output details. Most sentences earn their place, though it could be lightly tightened by grouping the many output-behavior clauses into a more scannable structure.

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

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

For a research tool with no output schema, the description is remarkably complete: it covers return shape, evidence fields, citations, gaps, contradictions, latency, authentication, depth semantics, and alternatives. An agent has enough information to select, invoke, and interpret results correctly.

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

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

Input schema coverage is 100%, so the baseline is 3. The description goes further by explaining the behavioral meaning of depth: 'quick=3 (single hop)', 'standard' adds gap recovery and contradictions[], and 'thorough' is paid and chases leads iteratively. It also clarifies that question accepts broad, multi-part natural language, which reinforces the schema's intent.

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

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

The description states a specific verb and resource: 'Grounded multi-source research across Pipeworx's 1506 STRUCTURED data sources' with a clear mechanism of decomposing questions, routing to tools in parallel, and returning a findings packet. It also explicitly distinguishes itself from ask_pipeworx, so an agent can immediately tell which tool fits.

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: 'Best for broad/multi-part questions over structured data,' and when-not-to-use guidance: single lookups, breaking/colloquial current news, and not being signed in. It names the alternative, ask_pipeworx, in each of those cases and even explains how depth controls iterative 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 declare readOnlyHint=true and idempotentHint=true; description adds that it returns top-N tools with full schemas, ready to call. 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?

Well-structured with core purpose first, though the list of domains is slightly lengthy but still concise overall.

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?

Complete for a discovery tool: explains return value (names, descriptions, schemas), callability, and usage 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% and description adds meaning: explains query as natural language, lists example domains, and mentions aliases.

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 finds tools by describing data or task, lists many domains, and distinguishes from siblings like search_within or suggest_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?

Explicitly says 'Call this FIRST when you have many tools available and want to see the option set', 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?

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the agent knows it is safe and non-destructive. The description adds valuable context: filings reflect the submitter's position and are not FCC decisions, and they are listed newest first.

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, no fluff. The first sentence states the core purpose, and the second adds an important nuance about the nature of filings. Every sentence earns its place.

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

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

Given that an output schema exists (so return values are covered), the description is mostly complete. It could mention pagination via limit/offset, but the 'newest first' ordering and inclusion of documents/parties are noted. A minor gap is the lack of pagination hint.

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 50%: only proceeding and _apiKey have descriptions. The tool description does not explain limit and offset, nor does it add meaning beyond what the schema already provides. The description lacks any parameter-specific guidance.

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 'List', the resource 'FCC ECFS filings', and the specific context 'in an exact proceeding/docket, newest first'. It distinguishes this tool from siblings like ecfs_search_filings and ecfs_filing_detail by focusing on a specific docket.

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

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

The description implies usage when an exact proceeding number is known, but it does not explicitly state when to use this tool versus alternatives like ecfs_search_filings (for searching) or ecfs_filing_detail (for a single filing). No guidance on prerequisites or limitations.

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 valuable context by listing the specific fields and data returned (e.g., 'official document/attachment URLs'), which supplements the annotations without contradiction.

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

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

The description is a single, well-structured sentence that front-loads the verb and resource, with no wasted words. It is concise and easily parseable.

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?

An output schema exists (per context), so return values are covered. The description lists the main fields, and the tool's simple one-item retrieval purpose is fully addressed. No gaps are apparent.

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 only 50% (only '_apiKey' has a description). The description does not add any parameter details beyond mentioning 'submission ID'; it lacks explanations of constraints or formats, failing to compensate for the low schema coverage.

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

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

The description uses the verb 'Retrieve' with resource 'one FCC ECFS filing', specifies the key parameter 'submission ID', and lists the included fields (proceedings, filers, authors, etc.). This clearly distinguishes it from sibling tools like 'ecfs_search_filings' and 'ecfs_docket_filings'.

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

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

The description implies use when you have a specific submission ID, but it does not explicitly state when not to use this tool or mention alternatives among the sibling tools.

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

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

Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds meaningful context: it uses the public API, returns public-record filings, and explicitly cautions that results are not FCC findings or endorsements. No contradictions with annotations.

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

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

Three focused sentences: what the tool does, how to choose between the two main parameters, and an important caveat. Every sentence earns its place, and key usage guidance is front-loaded.

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

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

With a rich input schema, output schema, and safety annotations, the description covers the essential selection and invocation context. It explains return content, main parameter behavior, and the public-record caveat, leaving no major gap 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 description coverage is 100%, so the baseline is 3. The description reinforces the filer/query distinction and exact-name semantics, but it mostly paraphrases what the schema already documents rather than adding substantially new meaning.

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

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

States a specific verb and resource ('Search FCC ECFS filings') and clearly distinguishes the two main search modes: filer-based exact-name lookup versus full-text query. This differentiates it from sibling tools like ecfs_search_proceedings and ecfs_filing_detail.

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 when to use 'filer' versus 'query', which is practical and actionable. It does not name sibling alternatives or state when not to use the tool, but the parameter-level guidance is clear enough for most selection needs.

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

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

The description adds behavioral context beyond annotations by stating the output includes descriptions, bureau, dates, and docket links. Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, and the description is consistent with these.

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

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and output. While very concise, it could benefit from slightly more structure to highlight the two search modes, but it is not verbose.

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

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

The description covers the primary use cases and, together with the output schema, provides sufficient context. It does not detail pagination or parameter combinations, but the annotations and schema fill in missing details. Given the tool's complexity, the description is complete enough.

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 60%, so the description partially compensates by mentioning 'exact number' and 'public API query' mapping to proceeding and query parameters. However, it does not explain limit, offset, or _apiKey beyond what the schema already provides, leaving some 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 it searches FCC ECFS proceedings/dockets by exact number or public API query and specifies the returned fields (descriptions, bureau, dates, docket links). This distinguishes it from sibling tools like ecfs_search_filings which focus on filings.

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 usage context by specifying two modes: exact proceeding number or public API query. However, it does not explicitly state when not to use this tool or mention alternatives among siblings, though the differentiation is implicit.

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

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

Annotations already declare this read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: it fans out across sources in parallel, uses sources_used/sources_failed to indicate real absence of data, returns empty sections for companies with no matching data, and falls back gracefully for private companies. It also explains that missing FDA-listed biologics is expected for small-molecule drug companies, not a bug.

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

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

The description is a single dense paragraph with many semicolon-separated clauses, and while it is front-loaded with trigger examples and a usage preference, the structure makes it harder to parse than necessary. It contains valuable information throughout, but the redundancy around accepted input shapes and the long parenthetical source list could be organized more cleanly.

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 present, the description carries the burden of explaining return behavior, and it does so thoroughly: it enumerates returned fields, describes sources_used/sources_failed, explains empty sections, covers input resolution for names, and defines failure semantics for private companies. It is complete enough for an agent to call the tool correctly and interpret the response.

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

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

The schema already fully describes both parameters at 100% coverage, so the baseline is 3. The description adds value by giving concrete examples ("AAPL", "0000320193", "Moderna"), clarifying that type accepts company or ticker interchangeably, and noting the resolved_from/resolved_to behavior when a name is provided. This goes slightly beyond the schema but largely reinforces it.

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

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

The description clearly states the tool's purpose: producing a full cross-source profile of a US public company in one parallel call. It names specific sources, output categories, and input forms, and it distinguishes itself from cheaper single-source lookups by explicitly saying it should be preferred when a holistic view is requested.

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

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

The description explicitly says when to use this tool: when the user asks for a holistic view, and it instructs the agent to prefer it over chaining single-pack SEC/XBRL/news lookups. It also covers boundary cases such as private companies returning resolved:false and notes rather than a bare failure, which helps the agent know how to interpret results.

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

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

Annotations provide destructiveHint=true and idempotentHint=true. Description adds context about clearing sensitive data and use cases, but does not contradict annotations.

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

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

Two sentences, no unnecessary words. Efficiently communicates purpose and usage.

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

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

For a tool with one required parameter and no output schema, the description fully covers purpose, usage context, and relationship to siblings.

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 schema already defines 'key' as 'Memory key to delete'. Description does not add 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?

Description uses specific verb 'Delete' and resource 'previously stored memory by key'. It clearly distinguishes from sibling tools 'remember' and 'recall'.

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

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

Explicitly states when to use: context stale, task done, clear sensitive data. Also advises pairing with remember and recall.

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 as safe. The description adds valuable behavioral context: fetches page, extracts title/description/key links, outputs standard format. No contradictions.

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

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

The description is concise (3-4 sentences), front-loaded with the main purpose, and every sentence adds value. No fluff.

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

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

Given the simplicity of the tool (2 params, no output schema, clear annotations), the description is complete: it explains input, process, output format, and use cases.

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

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

Schema description coverage is 100%, so schema fully documents both parameters. The description adds minimal extra meaning (e.g., example URL format, default/max for max_links) but does not go beyond schema details.

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 'generate' and the resource 'llms.txt file', and explains what it does (fetches, extracts, emits). It distinguishes from sibling tools like ai_visibility_check by focusing on producing a specific file format.

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

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

The description lists explicit use cases (client site, own project, competitor audit) but does not mention when not to use it or how it compares to alternatives like scan_competitor_ai_presence.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, indicating a safe read operation. The description adds context about default behavior (active subscriptions only) and the specific fields returned, which is valuable beyond the annotations.

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

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

The description is two sentences long, with the first sentence stating the action and return fields, and the second providing usage guidance. No redundant information, perfectly front-loaded and concise.

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

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

For a simple list tool with one optional boolean parameter and no output schema, the description fully covers what is needed: it states what the tool returns, the default scope, and when to use it. No gaps remain.

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

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

Schema coverage is 100% with one parameter (include_inactive) fully described. The description does not add additional semantics about this parameter beyond implying the default (active only). Baseline score of 3 is appropriate as the schema already handles parameter documentation.

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

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

The description clearly states the verb 'List' and resource 'the caller's active subscriptions'. It distinguishes from sibling tools like subscribe and unsubscribe by focusing on listing existing subscriptions. It also specifies the fields returned, leaving no ambiguity about what the tool does.

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

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

The description explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This provides clear context for when to use the tool. While it does not explicitly state when not to use it, the guidance is sufficient given the presence of sibling tools for subscribing and unsubscribing.

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 are all false and provide minimal signal, so the description carries the full burden. It discloses rate limits (5/day), free usage, token return without an account, later token-based retrieval behavior, and team review cadence. 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 lengthy but front-loads core purpose and usage. It includes some non-essential motivational lines (roadmap, quota) that prevent a perfect score, but remains well-organized and dense with useful information.

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

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

Despite no output schema, the description fully explains the return token workflow, rate limits, scope of applicability, message requirements, and provides enough context for an agent to use the tool correctly without additional documentation.

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 provides descriptions for all parameters (100% coverage). The description adds value by clarifying content guidelines (describe in terms of Pipeworx tools, don't paste the end-user prompt) and by explaining how to use claim_token as a follow-up invocation pattern, which goes 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 the specific verb 'Tell' and resource 'Pipeworx team', explicitly enumerates feedback types (bug, feature/data_gap, praise), and clearly distinguishes from all sibling tools, which are research or information tools. It leaves no ambiguity about what this tool does.

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

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

The description explicitly states when to use (bug, feature/data_gap, praise), provides exclusions by warning against reporting other MCP servers' tools and instructing to file those with the respective server, and gives a criterion for identifying Pipeworx tools. It also explains the claim_token workflow for follow-up, which is a usage pattern.

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 (readOnly, idempotent, non-destructive) are already present. Description adds valuable context: data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). This goes 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, well-structured: first states output, second lists use cases, third adds transparency. No unnecessary words; front-loaded with key 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 tool's simplicity (1 optional param, read-only, no output schema), the description covers purpose, usage, data source, caching, and parameter interpretation. No gaps for effective use.

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

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

Schema coverage is 100% for the single parameter. Description adds semantic guidance: 'Shorter windows surface what's hot right now; longer windows show steady-state demand.' This provides context beyond the enum values.

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

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

The description clearly states it returns top tools, packs, and call volume over a window, using specific verbs like 'returns' and 'calling on'. It distinguishes from sibling tools by focusing on trending usage rather than discovery or detailed 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?

Explicitly lists three use cases (discovering hot data, confirming canonical tool, aligning use cases). While it doesn't mention when not to use or alternatives, the guidance is clear and practical.

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 extensively discloses behavioral traits beyond annotations: fills check, Jaccard similarity filter, placeholder filter, partition check logic. Annotations (readOnlyHint, idempotentHint, destructiveHint) are consistent; no contradictions.

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

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

The description is quite verbose, mixing multiple concepts in a dense paragraph. While well-structured with a purpose first then modes, it could benefit from fewer words or bullet points for clarity. Redundancy exists (e.g., SEMANTIC ANCHOR explained twice).

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 (2 optional modes, no output schema), the description is remarkably complete. It explains response fields (opportunities[], partition_check), fill check mechanics, and edge cases (placeholder filtering). The agent has sufficient context 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%, but the description adds significant meaning beyond the schema: explains event slug usage, topic as seed question, cross-event mode details, and the absence of required arguments. This greatly aids the agent in selecting and invoking the correct 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: finding arbitrage opportunities on Polymarket via monotonicity violations and partition-sum checks. It distinguishes three modes (trending_scan, event, topic) with specific use cases, providing a precise verb+resource combination that differentiates it from siblings.

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

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

Explicit guidance is given: 'Call with NO args for a trending_scan', 'event (recommended for a specific market)', 'topic for cross-event scanning'. It also explains when not to trade via the fill check, providing 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?

The description goes far beyond annotations, detailing model families, edge calculations, tradeable-edge knobs, diagnostics, caching behavior, and explanation of why segments may be empty. Annotations already indicate read-only and idempotent, but the description adds rich operational detail.

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

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

The description is long but every sentence adds value. It is well-structured with clear sections for model families, response fields, and knobs. The first sentence front-loads the purpose, making it efficient for agent consumption.

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

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

Despite no output schema, the description explains the response structure (by_segment, fed_candidates, _diagnostics) and key fields. It covers caching, filtering logic, and edge attributes, providing a complete picture for agent invocation.

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

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

Schema descriptions cover all parameters (100% coverage), so the description adds minimal new per-parameter meaning. The overall context around knobs like min_liquidity and max_spread_pp is useful but not a substitute for schema-level detail.

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

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

The description clearly states the tool scans top Polymarket markets to return opportunities where Pipeworx data disagrees with market price. It is distinct from sibling tools like polymarket_arbitrage and polymarket_edge_tracker.

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 tool is described as 'built for what should I bet on today' and emphasizes discovery without paging hundreds of markets. While usage context is clear, explicit when-to-use vs alternatives is missing; still, the description implies its primary use case.

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

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

Annotations declare readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false. Description adds rich behavioral details: response structure (tracked, expired, snapshot_dates), meaning of fields (trend values, decay_pp_per_day absolute with sign convention), and limits (60-day TTL, snapshot start, daily closes vs intraday). 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?

Description is long but efficient. Front-loads key question and provides detailed response structure. Slightly verbose in response field explanations but no wasted sentences. Could be more structured with bullet points.

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, so description must explain return values. It thoroughly describes tracked[], expired[], and snapshot_dates[] with field meanings and edge cases (gaps indicate no scan). Complete given 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 description coverage is 100%. The description adds minimal extra: confirms defaults and max, but schema already documents both parameters fully. Baseline 3 applies.

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

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

Description clearly states it provides 'edge persistence and decay telemetry' and answers a specific question about edge age and shrinkage. It distinguishes from sibling polymarket_edges by focusing on time-series and decay, not just 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?

Explicitly answers 'how long has this edge existed and is it shrinking?' and contrasts fresh vs old edges. Gives a clear use case (different trades for same width at different ages). Does not explicitly state when not to use, but context is sufficient. Could mention alternatives like polymarket_edges for current snapshot only.

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?

Even though annotations already indicate readOnly, idempotent, and not destructive, the description adds behavioral details: requires one of market or event, explains return fields (e.g., verdict, forced_directional_risk), and warns about thin legs. 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 somewhat lengthy but well-organized with clear sections (SINGLE-MARKET, BASKET). It front-loads the purpose and requirements. Every sentence serves a purpose, though could be slightly trimmed without losing clarity.

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 thoroughly explains all return values and their significance, including edge cases like thin_legs and forced_directional_risk. It provides complete contextual understanding for an AI agent to correctly invoke and interpret 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 coverage is 100% (baseline 3). The description adds value by clarifying side defaults per mode and size interpretation ('max spend on buys, target proceeds on sells'). However, parameter meanings are already well-described in the schema, so the uplift is moderate.

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: 'Realizable-vs-theoretical edge check against live CLOB order-book depth'. It distinguishes itself from sibling tools by being a pre-trade risk check before acting on arbitrage signals or large trades.

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: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500'. Also explains the risk of partial basket fills converting arb into unhedged directional position, providing clear contextual guidance.

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

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

The description goes well beyond the readOnly/idempotent hints: it discloses the token-overlap matching method, the meaning of compatibility codes, conditions under which legs are skipped, the null semantics of temporal_alignment, the fees_note caveat, and that pre-mapped topics often return warnings. There is no contradiction with annotations.

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

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

The description is long but deliberately structured with TWO MODES, RESPONSE, SAFETY FIELDS, and clear code enumeration; this is justified by the tool's complexity. Slight redundancy exists around temporal_alignment_unknown and the warning to read compatibility fields, but no section is filler.

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

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

With no output schema, the description carries the burden of explaining the response shape, return fields, safety semantics, code meanings, skipped-leg counters, and fee caveats. It does all of this in enough detail that an agent can invoke both modes correctly and interpret results without additional source information.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: it explains how topic maps to both sides, how explicit parameters override the topic-mapped side, and that both modes run the identical token-overlap matcher. That is a genuine value-add over the schema descriptions.

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

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

The description states exactly what the tool produces: a cross-venue spread between Kalshi and Polymarket for the same resolving question, with two clearly named invocation modes. It also distinguishes this tool from broader arbitrage/edge tools by repeatedly scoping it to the same resolving question and equivalent bet shapes.

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

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

The description gives clear context and explicit mode-selection guidance: topic mode for 10 pre-mapped shortcuts, explicit event ticker/slug mode for custom pairings, with both running the same matcher. It does not explicitly compare against sibling tools like polymarket_arbitrage or polymarket_edges, so it stops short of full alternative-routing 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=true, idempotentHint=true, destructiveHint=false. Description adds value by stating scoping to identifier and usage context, with no contradiction.

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

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

Two sentences, efficient and well-structured. Every sentence adds value, with purpose front-loaded.

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

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

Given no output schema, description adequately explains return (value or list of keys). Could specify value format more, but sufficient for a simple 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% for the single parameter. Description adds meaning: 'omit to list all keys' and clarifies that key is the memory key to retrieve.

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 it retrieves a saved value or lists all keys. Distinguishes from sibling tools 'remember' and 'forget' by describing the retrieval function.

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

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

Provides clear when-to-use context (look up stored context) and examples. Mentions pairing with remember/forget, but does not explicitly state when not to use or list alternatives.

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

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

The description includes a side effect (mark_read:true sets events as read), which contradicts the annotation readOnlyHint: true. According to the rule, a description contradicting annotations scores 1, despite the description itself being transparent. This inconsistency could confuse agents about read/write semantics.

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

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

The description is three sentences, front-loaded with the main purpose. Every sentence adds useful context without redundancy. Highly 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 five parameters, no output schema, and a large sibling set, the description covers purpose, return format, parameter usage, alternative access method, and behavioral side effects. It is thorough for its complexity level.

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 beyond the schema by explaining return fields (source, citation_uri, payload) and clarifying the effect of mark_read, earning a slight bonus.

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

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

The description clearly states the tool pulls fired events from a subscription feed, specifying the verb and resource. It mentions return fields but does not explicitly distinguish from sibling tools like list_subscriptions or recent_changes, which may have overlapping functionality.

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 contextual guidance on polling and an alternative endpoint for scripts, but it lacks explicit when-to-use or when-not-to-use instructions relative to sibling tools. No exclusions or alternate tool recommendations are given.

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. Description adds substantial detail: fans out to SEC EDGAR, GDELT→GNews fallback, USPTO (soft-fail), behavior on relative dates, and output 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?

Description is informative but somewhat lengthy (multiple sentences). However, it front-loads example queries and every sentence adds essential detail. Minor conciseness improvement possible, but overall well-structured.

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

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

Despite no output schema, description specifies return structure (changes[] grouped by source, total_changes count, pipeworx:// citation URIs). It also describes fallback behavior and soft-fail for USPTO. For a complex multi-source tool, this is complete.

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

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

Input schema has 100% description coverage. Description adds value beyond schema: explains `since` accepts ISO or relative shorthand with examples, `value` accepts ticker or CIK, and `type` only supports 'company'. This enhances agent understanding.

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

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

Description states the tool provides 'change feed for a company in the last N days/weeks/months in ONE parallel call' and lists multiple user-facing examples. It explicitly distinguishes from sibling tool 'entity_profile', which serves static profile queries. The verb 'change feed' and resource 'company' are specific.

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 explicit when-to-use examples ('What's new with X', 'latest on Y', etc.) and directly states 'Use entity_profile instead when you want the static profile'. This clearly defines 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 already declare idempotentHint=true and destructiveHint=false. The description adds critical behavioral details: scoping by identifier, persistence duration (24 hours for anonymous, permanent for authenticated), and that it is a key-value store. 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?

Four sentences with no wasted words. The purpose is front-loaded, and each sentence adds distinct value: purpose, when to use, storage behavior, and usage with siblings.

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 purpose, usage guidance, behavior, and relationships with siblings. It does not explicitly describe the return value or success confirmation, which is a minor gap for a write operation. However, given the simple output (likely nothing or success), this is acceptable.

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 describes both parameters. The description adds value by providing examples of keys (subject_property, target_ticker) and clarifying that value accepts any text, which aids 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 a specific verb ('save', 'store') and defines the resource as key-value memory. It clearly distinguishes itself from sibling tools 'recall' and 'forget', and explains the scope across sessions.

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

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

The description explicitly states when to use the tool ('when you discover something worth carrying forward') and mentions pairing with 'recall' and 'forget' for alternatives. It lacks explicit 'when not to use' but provides sufficient context.

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

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

Even with readOnlyHint, openWorldHint, idempotentHint, and destructiveHint already set, the description adds substantial behavioral detail: cascading lookups, graceful degradation when GLEIF/OpenFIGI are unavailable, explicit `unresolved` reporting, returning `figi_candidates` rather than asserting a single match, and labeling identifiers by source. This goes well beyond the annotations.

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

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

The description is dense and front-loaded with example queries and the 'Use FIRST' directive. It is long and includes several embedded parentheticals, which slightly harms readability, but nearly every clause adds differentiating or operational detail.

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

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

Despite having no output schema, the description explains what is returned: canonical identifiers per entity type, source labels, unresolved identifiers, figi_candidates on ambiguity, and RxNorm citation information. It also covers input constraints, supported types, and failure degradation, so an agent has enough context to call it correctly.

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

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

Schema coverage is 100%, but the description adds high-value meaning beyond the schema: for bonds, value must be the issuer exactly as printed and not the full noun phrase; it gives concrete examples for ticker, CIK, and drug names; and it explains the ISIN-to-LEI resolution path. This materially improves correct invocation.

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 names a specific verb and resource: resolve a user-spoken name into canonical/official identifiers that other tools require. It immediately gives concrete example queries, enumerates supported entity types, and makes clear this is an ID-lookup tool distinct from profile or comparison siblings.

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

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

It explicitly instructs 'Use FIRST whenever you have a name but need an ID,' which gives strong and actionable context for when to invoke it. It also notes the tool replaces 2-3 manual lookups, but it does not explicitly contrast with sibling tools like entity_profile or compare_entities, so exclusions/alternatives are only partially covered.

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 value beyond annotations by describing the process: probes each entity, ranks by score, surfaces most/least recognized. Returns ranked list with score, confidence, signal density. 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?

Extremely concise: two sentences plus a usage example. Front-loaded with core purpose, no redundant information.

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

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

Despite no output schema, description adequately describes return format. Covers tool's role relative to sibling. Could mention limitations or prerequisites but overall 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?

With 100% schema coverage, description adds minimal extra meaning. Mentions 'your brand + N competitors' which aligns with entities parameter but does not explain models or _apiKey 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?

Specifically describes verb 'compare' and resource 'AI visibility across multiple entities'. Differentiates from sibling tool ai_visibility_check by stating it probes each entity with that tool and aggregates results.

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: 'Useful for competitive AI-marketing audits' with an example question. Implicitly suggests using ai_visibility_check for single probes but does not explicitly state alternatives or when not to use.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, etc.), the description discloses important behaviors: composite fan-out across multiple sources, potential timeout on bundlephobia's first measurement (5-30s), and graceful degradation (sources_failed listed if 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?

The description is one solid paragraph but packs a lot of information efficiently. It is front-loaded with the core purpose. Could be slightly improved with bullet-point structure for easier scanning, but still very concise and dense.

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 details the return values: summary block with specific fields, per-advisory detail, links, and alternative versions. It also covers partial failure behavior, making it complete for agent understanding.

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 covers both parameters with clear descriptions (package name default, version optional). Schema description coverage is 100%, so the description adds no critical new meaning beyond the schema. Baseline of 3 is appropriate.

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

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

The description clearly states the tool is a composite check for evaluating npm packages, listing specific data sources (deps.dev, bundlephobia) and returned fields. It distinguishes itself from siblings by being a one-call resource for safety/popularity/size questions.

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

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

The description explicitly tells when to use the tool: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me"'. It also states what the tool does NOT cover (non-npm ecosystems) and directs to an alternative (deps.dev:version) for other package managers.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive. The description goes beyond by detailing truncation at 200K chars, embedding model (BGE-base-en), overlapping windows (500 chars), and that truncated inputs are flagged. 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?

Front-loaded with main purpose, each sentence adds value (purpose, when-to-use, technical details). Slightly verbose with model and window details, but overall efficient and well-structured.

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

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

No output schema, but description explains that return includes passages with character offsets and similarity scores, which is sufficient. Covers input constraints (200K char limit, truncation), enabling correct agent usage.

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 description adds meaning: explains truncation behavior for 'text', provides example queries for 'query', and notes default for 'limit' (5). While schema already documents basics, the description enriches understanding with practical usage details.

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 verb ('semantic search'), resource ('inside a fetched record'), and distinguishes from siblings by specifying that it searches within already-pulled text. The description explicitly contrasts with other tools like 'ask_pipeworx_grounded', making the use case unambiguous.

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

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

Provides explicit guidance: use when a record is too large for the prompt, saves context, returns relevant passages with offsets for verification. Also describes how it pairs with 'ask_pipeworx_grounded', giving clear when-to and when-not-to context.

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

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

The description reveals important behaviors beyond annotations: account requirement, return of subscription id, delivery channels, SMS cap, webhook auto-disable after failures. This adds rich context to the annotations which already indicate write and non-destructive.

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 concise for the amount of information conveyed. It front-loads the purpose and requirement, then proceeds with type and delivery details. Minor redundancy with schema descriptions could be trimmed, 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 tool's complexity (multiple types, delivery channels, constraints), the description covers all necessary aspects: required account, type-specific parameters, delivery options with limitations, and return behavior. No output schema exists, but the description notes the new subscription id is returned.

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 description still adds significant value by providing concrete examples for each type (e.g., sec_8k items, polymarket_edge topic), constraints on delivery fields (phone verification, SMS cap, webhook HMAC details), and clarification that webhook secret is returned only once.

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

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

The description explicitly states 'Create a proactive monitoring subscription to a live-data event stream.' with clear verbs and resource. It lists specific types and distinguishes from sibling tools like list_subscriptions and unsubscribe.

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

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

The description states the requirement for a Pipeworx OAuth account and lists supported types with examples. It provides some context for when to use but does not explicitly exclude scenarios or contrast with sibling tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. Description adds valuable context about return content (category-bucketed examples from live catalog) and behavior (no arguments vs topic). 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 somewhat long but well-structured with bullet-like list of topics in parentheses and key action phrase upfront. All sentences add value; minor redundancy possible but still effective.

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?

Though no output schema, description fully explains what the tool returns, how to use it, and its role in the tool ecosystem (onboarding, learning meta-tools). Complete for its purpose.

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

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

Schema coverage is 100%, but description adds meaning by listing example topic values (finance, pharma, etc.) and explaining the effect of omitting the parameter (full spread). Also describes the return structure 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?

Description clearly states the tool returns category-bucketed example questions with exact tool+argument shapes. It positions itself as the onboarding entry point, distinguishing it from siblings like discover_tools or ask_pipeworx.

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 this FIRST when you do not yet know what Pipeworx can do for you'. Also clarifies when to use with/without the topic argument. Provides strong contextual guidance.

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

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

The description reveals key behavioral traits beyond annotations: ownership enforcement and that rows are deactivated (not deleted). Annotations indicate non-destructive mutation; the description adds nuance that historical events remain available. 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 two sentences long, front-loads the core purpose, and includes essential usage details without any fluff. 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 the tool's simplicity (single parameter, no output schema, clear annotations), the description covers all necessary aspects: purpose, usage constraints, and side effects. 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?

The input schema already includes a thorough description for the single required parameter ('Subscription id (uuid) returned by subscribe.'), achieving 100% coverage. The tool description adds no additional context about the parameter 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?

Description clearly states 'Cancel a subscription by id.' It uses a specific verb (cancel/unsubscribe) and identifies the resource (subscription). The sibling tools include 'subscribe' and 'list_subscriptions', making this tool's purpose distinct.

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

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

The description explicitly mentions ownership enforcement: 'you can only cancel your own subscriptions.' This provides clear context on when the tool can be used. It also explains that the row is deactivated, not deleted, which indirectly advises against using it if one expects deletion. However, it does not explicitly discuss alternative tools or when not to use 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description goes beyond these by explaining the meaning of two verdicts ('could_not_verify' indicates a pipeline failure with verification_error; 'unsupported' means the source coverage was searched and absent), which is critical for correct agent behavior. It also details the dual routing (SEC EDGAR vs grounded pipeline) and the return structure, providing rich behavioral context not present in annotations.

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

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

The description is compact yet information-dense. It front-loads purpose with examples, explains the two routing paths, lists verdicts, gives an important caller caveat, and concludes with efficiency benefit. Every sentence adds value; there is no redundancy or filler.

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

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

Given the tool's complexity (two processing paths, six verdict types, error semantics) and the absence of an output schema, the description is remarkably complete. It covers input examples, behavior by claim category, output structure (verdict, grounded/structured value, citation, reasoning), and failure-mode distinctions, enabling the agent to invoke the tool correctly and interpret results safely.

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 descriptions for both parameters are thorough, and the description adds further meaning, especially for tolerance_pct: it specifies the allowed range (0.5–50), how it overrides the wording-derived default, and a use case (set 1–2 for hallucination detection). This directly adds actionable guidance beyond the schema, which already has 100% coverage.

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

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

The description opens with natural-language query examples ('fact check', 'verify the claim that…') followed by a clear statement of purpose: 'natural-language claim verification against authoritative sources.' It explicitly distinguishes this from siblings by focusing on yes/no claim verification and describes its two processing paths (SEC EDGAR fast path and grounded pipeline), making it unmistakable what the tool does.

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

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

It explicitly tells when to use: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also provides a rule for when not to interpret a result as evidence ('could_not_verify means... must not be shown as one') and positions the tool as a replacement for 4–6 sequential calls, inherently guiding the agent to prefer this over multi-step alternatives.

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