Monarch Initiative

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses that the tool makes external API calls, the default model is free, and using Anthropic requires a BYO API key with direct cost to the user. This adds valuable behavioral context about cost and external dependencies.

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, each serving a distinct purpose: what it does, how to invoke extended functionality, and when to use it. There is no redundancy or filler, making it both concise and information-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 compensates by specifying the return structure (per-model {score, confidence, signals, raw_response} + combined view). It also covers input semantics, model options, cost, and practical use cases, making it complete for a tool of this complexity.

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

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

The input schema already provides 100% coverage with descriptions for all four parameters (entity, models, _apiKey, context). The tool description adds the default model and cost context, but these are also implied in the schema's model descriptions. The description does not add significant new semantics beyond the schema.

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

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

The description clearly identifies the tool's action ('Probe one or more LLMs'), the resource (business/brand/product/topic), and the output (visibility score 0-100 per model). It differentiates from siblings like scan_competitor_ai_presence by focusing on per-model scoring and a combined view.

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

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

The description provides explicit use cases ('AI-marketing audits, pre-launch brand checks, competitive monitoring') and explains how to invoke specific models (default Workers AI, optional Anthropic with _apiKey). It does not mention when not to use it or compare directly with sibling tools, so it stops short of a 5.

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

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

Annotations already indicate readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds meaningful behavioral context beyond annotations: it 'fills arguments', returns 'structured answer with stable pipeworx:// citation URIs', works on 'every tier', and makes 'one fast call'. This gives agents a clear model of what happens when the tool is invoked.

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 directive 'PREFER OVER WEB SEARCH' and is dense with actionable information. Every sentence earns its place: scope, routing mechanism, citation output, trigger phrases, examples, and escalation paths. Length is justified by the tool's broad applicability.

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 (a meta-router over 5,529 tools), no output schema, and rich annotations, the description fully covers when to use it, how it behaves, what it returns, and when to step up to alternatives. It also provides concrete examples and trigger phrases, making it complete for an agent to invoke correctly.

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

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

Schema coverage is 100% (all parameters are aliases for question with descriptions). The description adds examples but no additional parameter-level semantics beyond what the schema already provides. Baseline of 3 is appropriate when the schema fully documents parameters.

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

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

The description clearly states the tool's function with a specific verb and resource: it routes questions to one of 5,529 tools across 1,455 verified sources and returns a structured answer with citation URIs. It distinguishes itself from siblings like ask_pipeworx_grounded and deep_research by positioning itself as the default entry point.

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 to prefer this over web search for factual questions, provides the directive 'START HERE for most questions', and gives clear alternatives: 'use ask_pipeworx_grounded' for hallucination-resistant single answers and 'deep_research' for broad/multi-part questions. It also covers edge cases like breaking news, making usage guidance comprehensive.

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 valuable context beyond annotations: it explains the beta nature, the live candidate-testing mechanism, that no candidate is currently active, and that results are compared against the stable router. It also corrects any assumption that it might be a fallback by stating it is a full working router. This is beyond the read-only/idempotent hints provided.

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

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

The description is moderately sized, with three sentences, each carrying distinct information: identity, current state, and usage. It is front-loaded with the core purpose and avoids redundancy, though it is slightly verbose with the parenthetical details.

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

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

The description covers the tool's purpose, current behavior, usage guidance, and relationship to siblings. Since it references the identical response shape of ask_pipeworx, no output schema is needed. It is complete for an experimental router with good annotations.

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

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

The input schema already has full documentation for the 'question' parameter and its aliases, so the description adds little. It does mention 'same arguments' which is consistent, but doesn't elaborate further. Baseline of 3 is appropriate given high schema coverage.

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

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

The description clearly identifies this as the beta of ask_pipeworx, a universal router with the same tools, arguments, and response shape. It explicitly distinguishes it from the stable version by noting it carries experimental routing improvements and is currently identical since no candidate is active. This gives a specific verb+resource and differentiates from sibling '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?

It states to use this tool exactly like ask_pipeworx when wanting the newest routing, implying the stable version is for ordinary use. It also clarifies it is a full working router and not a fallback, preventing misuse. This is explicit enough guidance with an alternative tool named.

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 beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint) by detailing the exact return shape on success ({answer, evidence, confidence, source, fetched_at, refusal_reason:null}) and failure (explicit refusal with specific reason enums). It also discloses the cost implication of one extra LLM call, adding valuable context.

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

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

The description is longer than typical but each sentence carries operational value: it explains routing, extraction, output format, refusal reasons, use cases, and cost tradeoff. The structure is logical and front-loaded with the core purpose, making it readable despite length.

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

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

Despite no output schema, the description fully compensates by documenting the return object structure and all refusal reason codes. It covers purpose, process, usage context, and alternative selection, making it complete for agent decision-making.

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

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

Schema description coverage is 100%, with all parameters documented as aliases for 'question.' The description does not add additional parameter-level semantics beyond mentioning 'fills arguments' and natural language input, so the baseline of 3 applies.

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

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

The description clearly identifies the tool as a 'hallucination-resistant answer mode for high-stakes reads' and outlines its workflow: same routing as ask_pipeworx, picking tools, filling arguments, fetching data, then extracting the answer only from tool results. It distinguishes itself from sibling ask_pipeworx by mentioning the extra LLM call and the detailed output/refusal structure.

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

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

Explicitly states when to use: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' and when not to: 'prefer ask_pipeworx for casual lookups.' It also lists concrete use cases (financial verdicts, legal claims, medical lookups, public statements), providing strong 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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it fetches edges and supports filtering by category/predicate/direction, but does not disclose additional behavioral details like pagination, limits, or error cases beyond what annotations provide.

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

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

A single, front-loaded sentence that efficiently presents the core action and filtering capabilities with an example. No wasted words.

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

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

Given the output schema exists, return values need not be described. The description covers the main purpose, required parameter, and filters. However, the 'limit' parameter behavior is not mentioned, and the default direction is only in the schema, not the description. Minor gaps but still fairly complete.

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

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

Schema coverage is 60% with descriptions for category, direction, and predicate, but not for entity_id or limit. The description clarifies that entity_id is a CURIE ID, adding meaning, but limit remains unexplained. Overall, the description partially compensates for schema gaps but not fully.

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

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

The description clearly states the action ('Fetch'), the resource ('biolink associations (edges)'), and the input ('Monarch entity by its CURIE ID'). It also lists filtering options, distinguishing it from sibling tools like 'entity' or 'gene_to_disease'.

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 context: use when you need associations involving a Monarch entity, with optional filters. However, no explicit when-not-to-use or comparison to alternatives is given, so it does not fully meet the 'explicit alternatives' bar.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond this by disclosing parallel fan-out, response shape details, resolver confidence levels, low-confidence short-circuit behavior, closed/market handling, illiquidity flags, news fallback logic (GDELT 429, GNews), and cancellation-rule risk parsing. This is extensive behavioral context with no contradiction to annotations.

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

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

The description is well-structured with section headers (CLASSIFIERS, FAN-OUT EXAMPLES, RESPONSE SHAPES, etc.) and front-loaded purpose. However, it is exceptionally long (~300 words), and while most content is useful, it lacks conciseness for an agent that can already consult the schema. It is organized but not brief.

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

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

With no output schema, the description fully explains return values: result.market, result.analysis, result.evidence, market_match_confidence, parent_event, news fields, and status strings. It covers edge cases like wide spreads and cancellation rules, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining fan-out examples tied to the 'depth' parameter, clarifying 'include_raw' size tradeoffs, and restating the market parameter formats with examples. This extra context raises it above baseline to 4.

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

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

The description opens with a specific verb and resource: 'Research a Polymarket bet by pulling the relevant Pipeworx data for it in one call.' It clearly distinguishes from sibling tools by focusing on Polymarket bets and the integrated data fan-out. The usage examples ('should I bet on X') reinforce its purpose.

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

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

The description explicitly states when to use the tool: 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z".' It also provides fan-out examples and resolution-rule risk warnings that guide when to inspect specific fields. However, it does not name alternative tools or state when NOT to use this tool, so it lacks explicit exclusions.

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

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

Beyond the read-only/idempotent annotations, the description discloses data sources (SEC EDGAR/XBRL, FAERS), handles edge cases (off-calendar fiscal years), sort order by primary metric, and the return of paired data with citation URIs. It also states the efficiency gain ('Replaces 8–15 sequential lookups'), giving a complete behavioral picture without contradicting annotations.

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

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

The description is dense but every sentence earns its place: trigger examples, preference rule, data source details for both types, sort behavior, return format, and efficiency claim. It is front-loaded with core purpose and structured to separate company vs drug specifics.

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 covers return style (paired data + citation URIs) and sorting, but does not fully specify the response schema (e.g., exact field names, metric definitions). Minor gap for a tool with two entity types and a ranking output, but sufficient for an agent to select and invoke it.

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

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

Even with 100% schema coverage, the description adds significant meaning to the `type` parameter by explaining what data each type fetches and how results are ordered. It also provides concrete examples for `values` (tickers/CIKs, drug names), enriching the schema's enum and array 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 opens with explicit example queries and states 'side-by-side comparison of 2–5 companies or drugs in ONE parallel call.' It clearly identifies the resource (companies/drugs) and distinguishes from sibling single-entity lookups by adding 'ALWAYS PREFER over sequential single-pack lookups when comparing entities.'

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

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

It provides concrete trigger phrases ('Compare X and Y', 'X vs Y', 'rank these companies') and explicitly directs preference over sequential lookups. The description also differentiates behavior by type (company vs drug), giving users clear guidance on when each mode is appropriate.

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

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

The description discloses far beyond what annotations provide: account requirements, latency (15-60s, up to ~90s for thorough), the return format (findings packet with evidence, confidence, source, citation_uri, gaps[], contradictions[]), the second-hop gap-recovery behavior, and guarantees that citation_uri is always fetchable. It also explains semantic excerpting and the 'never invented' policy, with no contradictions to the readOnly/openWorld/idempotent hints.

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

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

The description is long but every sentence earns its place. It is front-loaded with account requirements and the primary alternative, then progressively explains the tool's mechanism, ideal use cases, depth behavior, output guarantees, and performance expectations. There is no filler or redundancy.

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

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

For a complex tool with no output schema, the description fully compensates: it explains the structure of the findings packet, includes limitations (news topics yield empty gaps[]), describes the iterative depth behavior, and even covers edge cases like citation fetchability and semantic excerpting. An agent has all necessary context 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?

Though schema coverage is 100%, the description adds critical semantic detail: the depth enum is fully explained with facet counts, hop behavior, and paid tier requirements, and the question parameter is clarified as natural-language and suitable for broad/multi-part queries. This goes well beyond the schema's brief 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 is explicit that this is 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' performed in one call, with decomposition into facets and parallel routing to 5,529 tools. It clearly distinguishes itself from open-web search and from sibling ask_pipeworx, making its purpose unambiguous.

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

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

It provides explicit when-to-use guidance: best for broad/multi-part questions over structured data, and explicitly tells users to use ask_pipeworx for single lookups or breaking/current-news topics. It also gives account-tier guidance, noting the paid requirement for depth:'thorough' and the fallback to ask_pipeworx when not signed in.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds valuable behavioral context: it returns full input schemas with curated examples, results are ready to call directly without a second lookup, and it returns a top-N ranked list. This goes beyond annotations and helps the agent understand the tool's output behavior.

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

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

The description is appropriately sized: it front-loads the core purpose, then provides concrete usage guidance and a domain list. Every sentence adds value, though the domain enumeration is slightly long. Overall it is well-structured and information-dense without being 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 tool is a discovery tool with no output schema, but the description explicitly outlines what the return value includes (names, descriptions, full input schemas with examples). It also covers when to use it, parameter behavior (limit, query aliases), and the 'ready to call' aspect. This is a complete picture for the agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema fully documents all parameters, including aliases and defaults. The description adds slight context by explaining the query is a 'natural language description' and that limit controls top-N size, but this overlaps with schema descriptions. Per the rubric, baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description opens with 'Find tools by describing the data or task,' which clearly states the verb (find) and resource (tools). It further distinguishes itself from siblings by framing itself as a meta-tool for discovering other tools, not performing data lookups. The domain list and mention of 'top-N most relevant tools' reinforce this purpose.

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

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

The description explicitly states when to use the tool: 'Use when you need to browse, search, look up, or discover what tools exist...' and 'Call this FIRST when you have many tools available and want to see the option set (not just one answer).' This gives clear context and even hints at timing (first), effectively guiding the agent away from alternatives.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, non-mutating, repeatable lookup. The description adds no behavioral context beyond the input format, so it does not contradict annotations but also does not enhance transparency beyond what annotations provide.

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

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

The description is one short sentence fragment, extremely concise with no wasted words. It is front-loaded with the core purpose. However, it is so terse that it omits usage guidance and context, so it loses a point for under-specification.

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

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

Given the tool's simplicity (one parameter, output schema present, annotations present), the description covers the basic lookup purpose. However, it does not address when to use this over siblings like 'search' or 'entity_profile', and lacks any mention of return behavior. The output schema covers return values, but the missing usage guidance makes it only minimally complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does by explicitly stating that 'id' is a CURIE and providing an example. This adds meaning beyond the bare schema property type 'string', although the schema examples also illustrate the format. The description clarifies the expected identifier scheme, which is valuable.

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 the tool returns a single node identified by a CURIE, e.g., 'MONDO:0007947'. This specifies the resource type (node) and the input format (CURIE), which is more specific than the title alone. However, it lacks an explicit verb like 'retrieve' or 'fetch', and does not clearly differentiate from sibling tools such as 'entity_profile' or 'resolve_entity'.

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 no explicit guidance on when to use this tool versus alternatives. It only implies usage for looking up a single node by CURIE. No exclusions, prerequisites, or alternative tools are mentioned, leaving the agent without clear selection criteria.

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

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

The description adds substantial behavioral context beyond annotations: it fans out across SEC EDGAR, XBRL, USPTO, news, GLEIF; mentions a soft-fail for patents due to API sunset; and describes the GDELT→GNews fallback for news. These details disclose operational behavior and failure modes that annotations do not cover, without contradicting the readOnly/openWorld/idempotent hints.

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

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

The description is dense but well-structured: it opens with example queries, then states the core function, lists sources and return fields, and closes with input constraints. Every sentence adds value (e.g., the patent sunset note, the resolve_entity pointer), and there is no redundancy. It is long but efficient for the complexity it conveys.

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

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

There is no output schema, but the description details the return structure: cik + company_name; recent_filings with URIs; fundamentals with specific fields and sorting; patents with a soft-fail note; news via fallback; and LEI. It also covers input constraints and alternatives. Given the tool's complexity, this description is exceptionally complete without an output schema.

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

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

Schema coverage is 100% (both type and value have detailed descriptions in the input schema). The description repeats the ticker/CIK format and the 'names not supported' rule without adding new semantic meaning beyond what the schema already provides. Thus the baseline of 3 is appropriate; the description does not compensate or extend parameter understanding.

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

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

The description clearly states the tool's function: 'full cross-source profile of a US public company in ONE parallel call.' It provides multiple example phrasings and explicitly distinguishes from sibling tools by saying 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' This makes the purpose specific and well-differentiated.

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

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

The description gives explicit when-to-use guidance: 'ALWAYS PREFER over chaining single-pack SEC/XBRL/news lookups when the user asks for a holistic view.' It also states an exclusion and alternative: 'names not supported (use resolve_entity first if you only have a name).' This clearly tells the agent when to choose this tool and what to do instead.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds the 'by key' scoping and the rationale for clearing sensitive data, but it does not disclose any unexpected behavior beyond what the annotations convey.

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

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

The description is three sentences, front-loaded with the primary purpose, followed by usage context and companion tools. Every sentence serves a purpose with no redundancy.

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

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

The tool is simple with one parameter and no output schema, and the description covers purpose, usage scenarios, and related tools. It does not mention behavior for non-existent keys, but the idempotentHint annotation covers this gap, making the description sufficiently complete.

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

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

Schema coverage is 100% and the parameter 'key' is described as 'Memory key to delete.' The description adds 'by key' but does not provide additional syntax, format, or edge-case details, so it adds minimal value beyond the schema.

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

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

The description opens with a specific verb+resource: 'Delete a previously stored memory by key.' This clearly states the action and target, distinguishing it from sibling tools like 'remember' (store) and 'recall' (retrieve).

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

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

The description explicitly states when to use the tool: 'Use when context is stale, the task is done, or you want to clear sensitive data the agent saved earlier.' It also names complementary tools ('Pair with remember and recall'), but does not explicitly state 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond those: it 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format.' It also states the output is a single text blob, which clarifies what the agent will receive. No contradiction with annotations.

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

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

The description is compact yet information-dense: it states the core function, the process, the output format, and concrete use cases in three sentences. Every sentence earns its place, and the most important information (what it does) is front-loaded. No fluff or redundancy.

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

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

With only two parameters and no output schema, the description covers all necessary context: input URL, optional max_links (implied), the fetching process, output format (single text blob), and even typical use cases. The tool's behavior is fully described for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond what the schema already provides. It mentions 'key links' and the output format, but the individual parameters (url and max_links) are sufficiently documented in the schema itself.

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

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

The description opens with a specific verb and resource: 'Generate a production-ready llms.txt file for any URL.' It clearly distinguishes itself from sibling tools by focusing on llms.txt generation and AI crawler indexing, which none of the listed siblings cover. The detailed breakdown of fetching and extracting content reinforces the unique purpose.

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

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

The description provides clear use cases: 'getting a client's site indexed by AI, drafting llms.txt for your own project, or auditing how an AI crawler would see a competitor.' This gives concrete when-to-use context. It does not explicitly mention when not to use or contrast with alternatives, but the use cases are sufficiently specific for an agent to decide.

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, covering the safety profile. The description adds the input format constraint (NCBIGene/HGNC) but does not disclose other behavioral aspects like possible errors or response characteristics.

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, succinct sentence that front-loads the core behavior and includes the essential input format. Every word earns its place with no redundancy.

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

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

Given the tool's simplicity (one required parameter, output schema present), the description is mostly complete. It clearly states the input format but does not mention what the output looks like; however, the output schema presumably covers that. No critical gaps for basic 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 description coverage is 0%, so the description must compensate. It does add meaning by specifying the expected format for gene_id (NCBIGene:… or HGNC:…), but it leaves ambiguity about whether bare gene symbols are accepted or how strict the format is.

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 indicates the tool returns diseases for a given gene and specifies the acceptable input formats (NCBIGene or HGNC). It is specific enough to distinguish from the reverse tool 'phenotype_to_gene', but it lacks an explicit verb like 'get' or 'list'.

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 use case is implied: when you have a gene identifier and want associated diseases. However, there is no explicit guidance on when to use this tool versus alternatives such as phenotype_to_gene, nor any mention of exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds valuable behavioral context by listing the exact returned fields and noting that it returns active subscriptions by default, while cancelled ones can be included via the include_inactive parameter. 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 three concise sentences. The first states the primary function, the second lists the return fields, and the third gives usage guidance. Every sentence earns its place with no redundancy or fluff.

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

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

For a simple list tool with one optional parameter, the description is fully complete. It specifies the resource scope (caller's active subscriptions), the default behavior (active only), the returned fields, and a practical use case. The presence of output fields in the description compensates for the lack of an output schema. Sibling tools provide additional context for when this fits into the subscription lifecycle.

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 (include_inactive), with a clear description in the schema: 'Include cancelled subscriptions in the response (default false).' The description does not add additional meaning beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the caller's active subscriptions.' It specifies the exact resource (subscriptions) and action (list), and the returned fields (id, type, params, etc.). It also distinguishes from sibling tools like subscribe and unsubscribe, which have different purposes.

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

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

The description provides explicit guidance on when to use the tool: 'Use this to review what you're monitoring before adding more or to find an id to cancel.' This gives clear context for use, though it does not explicitly mention when not to use it or name alternative tools. The sibling context (subscribe/unsubscribe) implies the alternative use cases.

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

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so no contradiction. The description adds the HP id format and directionality, but does not disclose any additional behavior such as handling of invalid IDs or return scope. This is adequate for a simple lookup but not rich behavioral context.

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

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

The entire description is a single, front-loaded sentence with no filler. Every word adds meaning, making it highly 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 one-parameter read-only lookup with a rich output schema and explicit annotations, the description is nearly sufficient. It tells the key input format and the relationship, but does not mention optional filtering, pagination, or source of annotations; however these are not needed for a minimal tool.

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

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

The schema only says phenotype_id is a string; the description clarifies it must be an HPO phenotype identifier of the form HP:…, which is essential semantic information. With only one parameter and 0% schema coverage, this compensates well, though it could state whether the full term or only the id is required.

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 resource (genes) and the input (HP phenotype id), and the title/direction distinguish it from sibling gene_to_disease. However, it lacks an explicit action verb like 'retrieve' or 'list,' making it a noun-phrase description rather than a clear command.

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?

No when-to-use or alternative guidance is provided; the intended use case (having an HP phenotype id and wanting associated genes) is only implicit in the mapping-style description. It does not mention when not to use it or available alternatives such as gene_to_disease or associations.

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

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

Annotations only set all hints to false, so the description carries the burden of behavioral disclosure. It adds significant context: filing returns a claim_token, the token can be passed back to read status, rate-limited to 5/day, free and not quota-counted, and the team reads digests daily. This goes well beyond the sparse annotations.

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

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

The description is longer than typical but every sentence serves a purpose: purpose, use cases, exclusions, claim-token workflow, rate limits, and quota. It's front-loaded with the core action and structured logically, though slightly verbose at 8 sentences.

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

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

For a feedback tool with no output schema, the description covers all necessary context: how to file, when excluded, what happens after filing, and how to follow up. It explains the claim_token lifecycle and operational constraints, making it complete for an agent to invoke correctly.

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

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

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds extra semantics for claim_token ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})' and 'with no other arguments') and advises message content ('don't paste the end-user's prompt'). This nudges it to a 4.

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

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

The description opens with 'Tell the Pipeworx team something is broken, missing, or needs to exist,' which clearly identifies the action and resource. It distinguishes from siblings by explicitly scoping to Pipeworx-only tools and excluding feedback for other MCP servers.

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

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

The description provides explicit when-to-use cases: 'Use when a tool returns wrong/stale data (bug), when a tool you wish existed isn't in the catalog (feature/data_gap), or when something worked surprisingly well (praise).' It also includes a strong when-not-to-use: if the tool came from a different MCP server, file it there, and explains how to identify Pipeworx 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, openWorldHint, idempotentHint, and destructiveHint=false. The description adds significant behavioral context: data is 'Self-aggregating signal — derived from CF analytics-engine, no PII, just (pack, tool, count)' and 'Cached 5min-1h depending on window.' This gives the agent expectations about data source, privacy, and freshness beyond the safety profile.

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

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

The description is structured with a purpose opening, a concrete 'Returns' statement, and three numbered use cases. Each sentence contributes value, though the opening rhetorical question 'What other AI agents are calling on Pipeworx right now?' is somewhat less crisp than a declarative start. Overall it remains efficient and front-loaded with the return type.

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

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

With no output schema, the description compensates thoroughly by listing the return contents (top tools, top packs, total call volume), the data format (pack, tool, count), the caching behavior, and PII disclosure. This is sufficient for an agent to understand what to expect without ambiguity.

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

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

The input schema fully documents the only parameter 'window' with enum values, a default (24h), and a description of tradeoffs between shorter and longer windows. The tool description merely repeats the enum options without adding new semantic depth, so the baseline of 3 applies due to high schema coverage.

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

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

The description clearly specifies the tool's function: 'Returns the top tools, top packs, and total call volume over a recent window (24h, 7d, or 30d).' It names a concrete resource (Pipeworx trending usage by other agents) and the specific output, distinguishing it from siblings like discover_tools or recent_alerts.

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

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

The description explicitly enumerates three use cases: discovering hot data sources, confirming canonical tool choice, and aligning with what most agents need. It also warns about caching ('Cached 5min-1h') which affects freshness expectations. However, it does not name alternative tools or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. The description adds rich behavioral context: the fill check warns that 'realizable_edge_pp ≤ 0 means the overround exists only at last-trade, not in the book; do not trade it,' and the semantic anchor prevents low-similarity pairing. These disclosures go far beyond annotations, making the tool's edge cases and failure modes explicit.

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 and dense, but it is structured into clear labeled sections (SEMANTIC ANCHOR, PARTITION FILTER, FILL CHECK) and front-loaded with the core purpose. Every section adds necessary operational detail. It slightly overpacks information into a single paragraph, but given the tool's complexity, the length earns its place.

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

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

Despite having no output schema, the description explains the response structure ('opportunities[] with gap_pp, suggested_trade, reasoning') and even describes the partition_check fields. It covers input modes, algorithmic details, filtering criteria, and trading caveats. For a complex tool with 0 required params and no output schema, this is exceptionally complete.

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

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

While the schema already provides 100% coverage for event and topic, the description adds substantial meaning: it clarifies that event takes a Polymarket event slug or full URL, offers example slugs ('fed-decision-may-2026'), explains the difference between event and topic behavior, and gives example seed questions for topic ('Strait of Hormuz traffic returns to normal'). This is a strong enhancement over the schema alone.

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

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

The description opens with a specific verb+resource: 'Find arbitrage opportunities on Polymarket via monotonicity violations + partition-sum checks.' This clearly distinguishes it from sibling tools like polymarket_edges (edge tracking) and polymarket_fill_risk (fill analysis). It also lays out three modes (trending_scan, event, topic) with concrete examples, 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 instructs when to use each mode: 'Call with NO args for a trending_scan... pass event for the strongest per-event partition_check, or topic for a themed cross-event scan.' It also names an alternative for sizing: 'For custom sizing use polymarket_fill_risk.' This gives clear decision guidance and alternatives, earning top marks.

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), the description extensively discloses behavior: three model families, response segments, diagnostics, caching ('Cached 1h at the KV level keyed on all knobs'), the 24h-move warning, relaxed gates from Run 8, placeholder filters, and the unreliability of Fed bets without paid data. 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 a massive single paragraph densely packed with details, which is informative but not concise. It front-loads purpose and then dives into deep model mechanics. While every sentence contains useful information, the lack of structure (bullets/headings) makes it harder to parse, and it is significantly longer than necessary for a tool description.

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

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

Given 9 parameters, no output schema, and complex internal logic, the description is remarkably complete. It explains the response top-level (by_segment, fed_candidates, _diagnostics), the purpose of diagnostics, the filtering knobs, and caveats like the Fed note. It covers all relevant aspects an agent needs to 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?

Even though schema coverage is 100%, the description enriches parameter semantics by grouping them as 'TRADEABLE-EDGE KNOBS' and explaining their interplay, e.g., min_partition_leg_kelly applies to per-leg Kelly inside partitions because parent-level kelly_fraction_half is always 0. This adds value beyond the schema's already detailed parameter descriptions.

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

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

The description clearly states the tool's purpose: 'Scan top Polymarket markets and return opportunities where Pipeworx data disagrees with market price.' It also gives a concrete use case ('what should I bet on today'). However, it does not explicitly differentiate itself from sibling tools like polymarket_arbitrage or polymarket_edge_tracker, relying instead on the unique description of model families and output structure.

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

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

The description provides clear usage context: 'discover opportunities without paging hundreds of markets' and describes the intended agent scenario. It also explains the knobs for filtering tradeable edges. It does not explicitly say when NOT to use this tool or name alternatives, but the context is sufficient for an agent to decide when to invoke 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 the tool readOnly, openWorld, idempotent, and non-destructive, but the description adds detailed behavior: snapshots are written on cache-miss, gaps mean no scan that day, history depth is bounded by a 60-day TTL, and decay is computed from daily closes not intraday. 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 stays relevant: it front-loads the purpose, then labels Args, RESPONSE, and LIMITS sections. Every sentence adds contextual or behavioral information necessary for a tool with no output schema.

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

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

The response format is fully specified (tracked[], expired[], snapshot_dates[] with field semantics), and limits are disclosed (TTL, daily closes, cache-miss gaps). This compensates for the absence of an output schema and covers all operational context.

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

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

Input schema covers both parameters with descriptions, so baseline is 3. The description replicates the defaults ('default 14, max 30', 'default 1wk') and adds the concept of 'snapshot family' but no additional meaning beyond the schema.

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

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

The opening sentence states 'Edge persistence and decay telemetry built from daily polymarket_edges snapshots' and answers 'how long has this edge existed and is it shrinking?' This clearly specifies the verb (tracks persistence/decay) and resource (polymarket edges snapshots), distinguishing it from sibling tools like polymarket_edges.

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

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

The description frames the tool's use case around a specific question: 'how long has this edge existed and is it shrinking?' and explains why edge age matters ('a fresh wide edge and a 3-week-old wide edge are different trades'). It notes limits like TTL and snapshot gaps, giving context for when results are reliable, though it doesn't explicitly name alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description adds substantial behavioral context beyond that: it walks the order-book ladder, calculates VWAP, returns a verdict (clean|degraded|cannot_fill), and explicitly warns that partial basket fills convert an arb into an unhedged directional position. These are genuine behavioral disclosures not captured by 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?

Although lengthy, every sentence serves a purpose. The description is front-loaded with the core purpose, then clearly organized into SINGLE-MARKET and BASKET sections, and ends with practical usage guidance. No filler or repetition exists; the density is appropriate for a tool with two distinct modes.

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 modes, 4 parameters, no output schema) and that annotations are already strong, the description is exceptionally complete. It enumerates return fields (theoretical_sum vs realizable_sum, capture_ratio, profit_usd, thin_legs[], max_clean_notional_usd), highlights failure mode (cannot_fill, forced_directional_risk), and ties to real-world usage patterns. This exceeds what a typical description provides.

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

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

Schema coverage is 100%, but the description enriches every parameter. It explains that `market` selects single-market mode and `event` selects basket mode, clarifies the default and interpretation of `side` for each mode, and details how `size_usd` behaves differently for buys vs sells and single vs basket (settlement notional, shares per leg). It also states the default (1000) and clamp range (10–1,000,000), going far beyond the schema.

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

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

The description opens with a specific verb+resource: 'Realizable-vs-theoretical edge check against live CLOB order-book depth.' It clearly distinguishes single-market vs basket/partition modes and names concrete return fields (top_of_book, vwap_fill_price, slippage_pp, verdict). This fully differentiates it from sibling tools like polymarket_arbitrage and polymarket_edges.

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

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

Explicit when-to-use guidance is given: 'USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500.' It also explains why (theoretical overround on thin books is not capturable, partial fills create unhedged directional risk), providing clear context for when this tool is needed over 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 indicate read-only, open-world, idempotent, and non-destructive behavior. The description goes well beyond this by explaining compatibility_warning conditions, temporal_alignment semantics, skipped_cross_type/subtype counters, and the caveat that pre-mapped doesn't mean tradeable. No contradiction with annotations.

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

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

The description is long but well-structured with labeled sections (TWO MODES, RESPONSE, SAFETY FIELDS) and is front-loaded with the core purpose. Every caveat earns its place, but some redundancy exists with the schema's shortcut list, making it slightly less concise than ideal.

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

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

With no output schema, the description fully explains the response format including leg-by-leg prices, top_spreads_pp, compatibility_warning, temporal_alignment, and skip counters. It also addresses edge cases like meaningless temporal gaps and non-equivalent bet shapes, making it complete for a tool of this complexity.

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

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

Schema coverage is 100%, but the description adds mode semantics: topic shortcuts auto-fetch matching events while explicit ticker/slug override the mapped side. It clarifies the relationship between topic and overrides, though the shortcut list is duplicated from the schema.

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

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

The description clearly identifies the tool as computing the cross-venue spread between Kalshi and Polymarket for the same resolving question, specifying the scope (equivalent bet shapes) and two modes. It distinguishes itself from a simple arbitrage tool by explaining when the delta is a real signal versus when the tool flags non-equivalence.

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

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

The description provides clear context for when to use the tool: comparing the same outcome across venues, with two explicit modes and a strong warning that pre-mapped shortcuts often return compatibility_warning and are not tradeable. It gives clear when-not guidance but does not explicitly name alternative 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, idempotentHint, and destructiveHint, so the bar is lower. The description adds useful context about scoping (anonymous IP, BYO key hash, or account ID) and the listing behavior when the key is omitted. No contradictions with annotations.

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

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

The description is three concise sentences, front-loaded with the main action, and every sentence provides useful information without redundancy or fluff.

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

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

For a simple read tool with one optional parameter and no output schema, the description provides comprehensive coverage: purpose, usage context, scoping, and relationships to sibling tools. Nothing essential is missing.

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

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

The schema covers the key parameter with 100% description coverage, providing a solid baseline. The description adds value by giving concrete examples of typical keys (ticker, address, research notes) and clarifying the omit-key-to-list behavior, which enhances understanding beyond the schema.

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

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

The description clearly states the tool's function with a specific verb ('Retrieve') and resource ('a value previously saved via remember'), and also covers the alternative listing behavior. It distinguishes itself from sibling tools like remember and forget.

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

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

It explicitly describes when to use the tool ('look up context the agent stored earlier') and names related tools (remember for save, forget for delete), but does not explicitly state when not to use it or list exclusions beyond that.

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 explicitly states that setting mark_read:true flags returned events as read, a side effect that modifies state. However, the annotations declare readOnlyHint:true, implying the tool never mutates data. This is a direct contradiction between the description and annotations. Per the rubric, this mandates a score of 1.

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 and front-loaded with the core purpose, followed by return details, filtering, mark_read behavior, and an alternative access point. Each sentence carries useful information, but it is a bit longer than necessary; a sentence about the alternative URL could be moved or trimmed. Still, it is well-structured and without fluff.

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

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

Despite having no output schema, the description thoroughly explains what the tool returns (source, citation_uri, raw payload), provides filtering guidance, clarifies the side effect of mark_read, and offers an alternative URL for scripts/dashboards. Combined with thorough annotations (readOnlyHint, idempotentHint, openWorldHint) and 100% schema coverage, the description is complete for a list/feed tool.

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

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

Schema coverage is 100% with descriptions for all 5 parameters. The description adds extra meaning beyond the schema by explaining the effect of mark_read (flagging read so next call shows newer ones) and contextualizing filter type with an example (sec_8k). It also describes the return payload, enriching the parameter context. This goes slightly beyond the baseline 3.

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

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

The description opens with a specific verb phrase 'Pull fired events from your subscription feed', clearly identifying the tool's action and resource. It also distinguishes itself from siblings like list_subscriptions or recent_changes by focusing on alerts from subscription feeds and describing their content (source, citation_uri, raw payload).

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

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

The description provides clear context on when to use the tool: for polling recent alerts, with filtering options, and mark_read. It does not explicitly name a sibling alternative but indicates an alternative HTTP endpoint for scripts/dashboards, which offers practical guidance. However, it lacks explicit exclusions or when-not-to-use guidance, so it misses a 5.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive hints. The description adds significant behavioral detail beyond that: fans out to SEC EDGAR, GDELT/GNews (with fallback conditions), and USPTO (including the API sunset causing soft-fail). It also discloses the parallel execution and return format, which annotations do not provide.

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

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

The description is dense but well-organized: starts with user intent, then states the core action, enumerates sources and fallbacks, explains the key parameter format, describes the return shape, and ends with an explicit alternative. Every sentence adds distinct value; no filler or repetition of schema fields.

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 states the return structure (changes[], total_changes, citation URIs). It covers the multi-source behavior, fallback logic, the `since` format, and parameter semantics. It also provides a pointer to the sibling tool that covers the static-profile use case, making the description self-sufficient for the tool's complexity.

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

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

Schema coverage is 100% with useful parameter descriptions, but the description adds extra nuance: it clarifies 'since' accepts ISO dates and relative shorthand with concrete examples ('7d', '30d', '3m', '1y'), and for 'value' gives examples of ticker and zero-padded CIK. This enriches the schema beyond baseline.

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

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

The description opens with concrete user intents ('What's new with X', 'latest on Y') and then clearly states the tool's function: a change feed for a company over a window in one parallel call. It explicitly distinguishes this from sibling tool entity_profile by directing users to that tool for static profiles.

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 signals via example queries ('news on Tesla recently') and explicitly says to use entity_profile instead when a static profile is needed 'regardless of window.' Also describes fallback behavior (GDELT→GNews, USPTO soft-fail) which sets expectations for when and how to rely on 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 already indicate idempotent and non-destructive; description adds persistence semantics (authenticated vs 24-hour anonymous), scoping by identifier, and key-value storage format. No contradiction, additional context beyond annotations.

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

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

Three sentences, front-loaded with primary action, no filler. Covers purpose, usage, persistence, and companion tools efficiently.

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?

Handles a simple key-value store well: explains when/why, storage scope, retention, and related tools. No output schema mentioned, but the operation is straightforward; slight gap on return value/overwrite behavior, but not critical given annotations.

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

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

Schema covers both key and value with clear descriptions and examples, so baseline is 3. Description adds general storage semantics but no parameter-specific details 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 uses specific verb 'Save' and resource 'data the agent will need to reuse later,' clearly distinguishing from sibling tools like recall (retrieve) and forget (delete). It mentions explicit use cases and scope, making purpose unambiguous.

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

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

Explicitly states when to use ('Use when you discover something worth carrying forward') and provides companion tools 'recall to retrieve later, forget to delete.' This is a model for usage guidance.

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

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

Beyond the annotations (readOnly, openWorld, idempotent, non-destructive), the description adds valuable behavioral context: identifiers are source-labelled, unresolved identifiers are explicitly returned, and GLEIF/OpenFIGI enrichment degrades gracefully with EDGAR identifiers still returned. This exceeds the minimum needed.

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

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

The description is longer than average but well-structured: example queries first, then purpose, then detailed supported types and failure behavior. Every sentence contributes meaningful information, though some redundancy exists in the example list. It remains efficient and front-loaded.

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

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

With no output schema, the description carries the full burden of explaining return behavior. It covers both supported types, the `unresolved` field, source labelling, graceful degradation, and the cascading nature of lookups. This is complete for a tool with two parameters.

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 both parameters, so baseline is 3. The description adds significant value by giving concrete examples (ticker, CIK, drug names), clarifying the accepted value format for each type, and explaining what each type resolves to, enriching the schema descriptions.

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

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

The description clearly states the tool's purpose: 'resolve a user-spoken NAME to the canonical/official identifiers other tools require as input.' It provides concrete example queries and distinguishes itself from sibling tools by positioning as the name-to-ID lookup, reinforcing with 'Use FIRST whenever you have a name but need an ID.'

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

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

The description gives an explicit usage directive: 'Use FIRST whenever you have a name but need an ID.' It also notes the tool replaces 2-3 manual lookups. However, it does not name alternative tools or explicitly state when not to use it, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false. Description adds meaningful behavioral context: it probes each entity with ai_visibility_check, ranks by score, and returns a ranked list with score, confidence, and 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?

Three sentences, front-loaded with purpose, includes an example and return format. No filler or redundancy.

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

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

With 4 params and no output schema, the description compensates by stating the return structure (ranked list with score, confidence, signal density) and providing a concrete use case. Missing edge cases or rate limits, but adequate for moderate 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%, so baseline is 3. Description reinforces the entities parameter ('your brand + N competitors') and the 'first entry treated as subject' rule, but adds no new parameter information 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 a specific verb and resource: 'Compare AI visibility across multiple entities side-by-side.' It distinguishes itself from sibling ai_visibility_check by focusing on multi-entity comparison and from compare_entities by targeting AI visibility specifically.

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

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

Provides a clear use case: 'Useful for competitive AI-marketing audits' with an example query. It implies single-entity checks would use ai_visibility_check, but does not explicitly state when not to use this tool or name alternatives.

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

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

Beyond the annotations (readOnlyHint, idempotentHint), the description adds critical behavioral context: partial failures degrade gracefully, bundlephobia's first measurement can take 5-30s, and 'sources_failed' will list timeouts. This is exactly the kind of operational nuance the agent needs.

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

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

The description is dense but every sentence earns its place: it covers purpose, usage, return fields, ecosystem limitations, and failure behavior in a compact paragraph. No redundant or filler content.

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

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

Since there is no output schema, the description fully enumerates the return structure (summary block fields, per-advisory detail, links, alternative versions). It also covers ecosystem scope and error handling, making it complete for a composite tool of this complexity.

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

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

The input schema already covers both parameters with descriptions (package, version) including default behavior. The description adds no additional parameter-level guidance, but with 100% schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states it is a composite 'should I add this npm package' check, with a specific verb (scan), resource (npm package), and scope (deps.dev + bundlephobia). It distinguishes itself from sibling tools by focusing on dependency evaluation, which none of the siblings address.

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

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

Explicitly states when to use ('Use whenever an agent asks is X safe / popular / small') and provides exclusions ('NPM ecosystem only... PyPI/Maven/Cargo/Go fall under deps.dev:version directly'). This gives clear direction for selecting this tool over alternatives.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and idempotency. The description adds behavioral context about full-text search, category filtering, and pagination, but does not disclose additional traits like rate limits, auth requirements, or result format (which is handled by the output schema). This is consistent with the expected bar when annotations are present, providing some extra value but not deeply expanding beyond them.

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

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

The description is a single, front-loaded sentence that immediately states the action and resource. Every phrase adds useful information (entity types, filtering, pagination) without redundantly repeating schema details. It is concise and well-structured.

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

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

Given the tool's moderate complexity (4 params, 1 required), existing annotations, and an output schema, the description covers all essential aspects: scope, filtering, and pagination. It does not explain explicit differences from sibling tools, which is a minor gap, but the description is otherwise complete enough for an agent to invoke the tool correctly.

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

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

The schema has descriptions for only 'limit' and 'category' (50% coverage), leaving 'query' and 'offset' undocumented. The description compensates by explaining 'query string', 'filter by category', and 'paginate with limit/offset', thereby covering all four parameters conceptually. It adds value beyond the schema by explicitly tying the parameters to the search behavior.

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

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

The description specifies a clear verb ('search') and resource ('Monarch biomedical knowledge graph'), and details the scope ('diseases, genes, phenotypes, and other biolink entities'). It also mentions filtering and pagination, which distinguishes it from generic search tools. This is a specific, non-tautological statement of purpose.

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

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

The description clearly indicates when to use the tool: for full-text search across the knowledge graph by query string. It mentions filtering by category and pagination, giving a clear context of use. However, it does not explicitly compare against siblings like 'search_within' or 'deep_research' to exclude them, so it stops short of full when-not-to-use guidance.

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

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

Beyond the annotations (which only declare safe read-only/idempotent behavior), the description discloses concrete algorithmic details: BGE-base-en embeddings, cosine similarity over 500-char overlapping windows, a 200K character cap with truncation flagging, and that every passage includes offsets for verbatim verification. This gives the agent a thorough understanding of what the tool does internally and what to expect.

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

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

The description is front-loaded with the core purpose in the first sentence, then covers usage, companion workflow, and technical constraints in a structured, dense manner. Every sentence contributes unique information, and there is no fluff or redundancy. It is appropriately sized for the tool's complexity.

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

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

With no output schema, the description compensates by specifying the return format (top-N passages with character offsets and similarity scores). It also covers the input size cap, truncation behavior, and intended pairing with ask_pipeworx_grounded. For a three-parameter tool, all essential aspects are addressed.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds value by providing concrete examples for the 'text' parameter (e.g., SEC 10-K body, article) and by linking the 'limit' parameter to the phrase "top-N passages." It enriches the schema without repeating it, though it doesn't individually describe each parameter beyond the schema.

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

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

The description states a specific action ("Semantic search INSIDE a fetched record") and clearly identifies the resource (a text record already pulled). It distinguishes from sibling search tools by emphasizing the input is already-fetched content and by explicitly mentioning a complementary tool (ask_pipeworx_grounded), making the purpose unmistakable.

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

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

The description gives explicit when-to-use guidance: "Use when the record is too big to cram into the prompt — search_within saves context". It also names an alternative/complementary workflow (fetch with the gateway, ground over passages with ask_pipeworx_grounded), giving the agent clear decision rules and context for when this tool is appropriate.

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

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

Annotations already indicate readOnly=false, idempotentHint=true, and destructive=false. The description adds significant context beyond these booleans: requires a Pipeworx OAuth account, anonymous/BYO limitation, SMS phone verification and 10/day cap, webhook signing secret issued once, and auto-disable after 10 failures. No contradiction with annotations.

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

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

The description is dense but well-structured and front-loaded: it opens with the core purpose, then return value, auth requirement, supported types with examples, and delivery channel details. Every sentence provides operational value, and the length is justified by the tool's complexity.

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

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

With 3 parameters, nested objects, and no output schema, the description is comprehensive: it explains all subscription types, parameter shapes, delivery options, auth prerequisites, rate limits, return values, and webhook security details. An agent has enough information to invoke it correctly without additional 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?

The input schema covers all 3 parameters with 100% description coverage, including type-specific examples and delivery channel details. The tool description largely mirrors this information without adding new parameter semantics, so the schema carries the load; baseline 3 applies.

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

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

The description clearly states the action (create a proactive monitoring subscription), the resource (a live-data event stream subscription), and the scope (multiple subscription types). It distinguishes itself from sibling tools like list_subscriptions and unsubscribe by focusing on creation, and explicitly returns the new subscription id.

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

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

It provides context on when to use the tool by noting the OAuth account requirement (anonymous/BYO cannot persist subscriptions) and mentions an alternative pull mechanism via recent_alerts or a direct GET. However, it does not explicitly name or contrast with subscription-management sibling tools like list_subscriptions or unsubscribe, so exclusion guidance is implicit rather than explicit.

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

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

Annotations already provide readOnly, openWorld, and idempotent hints. The description adds meaningful context: it returns category-bucketed example questions, draws from the live catalog of thousands of tools, and lists the exact output content. No contradiction with annotations.

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

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

The description is dense and front-loaded with example phrasings, but remains well-organized with em-dashes and a clear flow. Every sentence contributes, though the length is on the higher side for a tool with one optional parameter.

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

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

Covers purpose, invocation modes, output contents (bucketed questions with tool shapes), and relationship to sibling tools. Even without an output schema, the description fully explains what to expect and when to call this tool.

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

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

The single optional parameter `topic` is fully documented in the schema, including the enum-like list and the omit behavior. The description adds only minor examples ('finance', 'pharma', 'betting') without introducing new syntax or semantics, so the baseline of 3 is appropriate.

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

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

The description clearly identifies the tool as the onboarding entry point that returns category-bucketed example questions with exact tool and argument shapes. It distinguishes itself from sibling meta-tools like ask_pipeworx and discover_tools by emphasizing 'Use this FIRST'.

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

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

Explicitly states when to use: 'Use this FIRST when you do not yet know what Pipeworx can do for you,' and names alternatives like ask_pipeworx, entity_profile, and compare_entities. Also explains invocation modes: no args for full spread or pass a topic to focus.

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

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

Annotations already indicate non-read-only, non-destructive, and idempotent behavior. The description adds crucial behavioral details beyond annotations: ownership enforcement, deactivation rather than deletion, and that historical events remain accessible via recent_alerts. This enhances understanding of the operation's effects and constraints.

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, with the core action front-loaded ('Cancel a subscription by id'). Each subsequent sentence adds distinct value: ownership enforcement and deactivation semantics. 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?

For a single-parameter tool with no output schema, the description sufficiently covers the operation, ownership requirement, and post-cancellation data availability. It does not explicitly describe the return value or error handling, but given the simplicity and annotations covering idempotency, this is a minor gap.

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 describes the 'id' parameter as a subscription uuid. The description adds the important semantic that the id must belong to the caller ('you can only cancel your own subscriptions'), which is a constraint not present in the schema. This augments the parameter meaning beyond the basic type description.

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

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

The description clearly states the function: 'Cancel a subscription by id.' It distinguishes itself from siblings like subscribe and list_subscriptions by specifying the action and resource. The additional details about ownership and deactivation further clarify its unique behavior.

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

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

The description provides clear context on when to use the tool: to cancel a subscription the user owns. It also gives a relevant alternative/consequence by noting that historical events remain available via recent_alerts, which helps the agent decide between cancellation and other actions. It does not explicitly name an alternative tool but the guidance is sufficient.

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/openWorld/idempotent annotations by explaining the verdict taxonomy, the distinction between could_not_verify and unsupported, the dual-path pipeline (SEC EDGAR vs grounded), and the returned citation format. It even warns against misinterpreting could_not_verify as evidence, adding critical behavioral nuance.

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 on the longer side, but it is well-structured: it leads with trigger phrases and purpose, then explains pathways, outputs, and critical caveats. Every sentence adds value, especially the caveat about could_not_verify. The length is justified by the tool's complexity, though it could be tightened slightly.

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 tool's behavior comprehensively: return values (verdict, value, citation, reasoning), error handling, routing logic, and typical use cases. With no output schema, the description fully compensates by explaining the expected outputs and edge cases, making it complete for an agent to invoke correctly.

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

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

The input schema already provides 100% coverage with detailed descriptions for both parameters (claim and tolerance_pct), including examples and default behavior. The tool description adds context about how claims are processed but does not materially enhance the parameter meanings beyond what the schema already states, so the baseline of 3 applies.

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

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

The description clearly states the tool's function with specific verb phrases (e.g., "fact check", "verify the claim that…") and a well-defined resource (natural-language claims verified against authoritative sources). It also distinguishes itself from a multi-step alternative by mentioning it replaces 4–6 sequential calls, making the purpose highly 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?

The description explicitly says "Use whenever the agent needs to check whether something a user said is factually correct." It also provides context on how different claim types are routed, but does not name sibling tools or explicitly state when not to use it, so it's clear context without formal exclusions.

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