Realestate

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

Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds crucial behavioral details: the free default model, the need for a BYO Anthropic API key, and the return structure (per-model details plus combined view). 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 four sentences, front-loading the core action and purpose. Every sentence adds value without redundancy, achieving high information density.

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 (4 params, no output schema) and the richness of the description covering purpose, parameters, behavior, return format, and use cases, the description is fully complete for an agent to select and invoke the tool.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining the default for 'models', the purpose of '_apiKey', and how 'context' disambiguates entities. This justifies 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 clearly states the tool probes LLMs for knowledge about an entity and scores visibility, with a specific verb and resource. It distinguishes from sibling tools like scan_competitor_ai_presence by focusing on visibility scoring across models.

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

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

The description provides explicit use cases (AI-marketing audits, pre-launch brand checks, competitive monitoring) and implies when not to use (e.g., if you need a simple answer rather than a visibility score). However, it does not explicitly exclude alternatives or provide direct comparisons to siblings.

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

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

The annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds useful context about routing, argument filling, return format with citations, and performance expectations ('one fast call'), without contradicting any annotation.

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 most important instruction ('PREFER OVER WEB SEARCH') and every sentence conveys decision-relevant information. It is lengthier than necessary due to repeated emphasis on 'start here' and 'use whenever', but the structure is clear and scannable.

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

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

For a router tool with no output schema, the description is remarkably complete: it covers when to use, when not to use, alternative tools, supported domains, example prompts, and the return format with citations. The agent has everything needed to select and invoke the tool correctly.

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

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

The schema already covers all six parameters (question plus aliases) with 100% description coverage, so the baseline is 3. The description adds value by providing concrete example questions and broad domain guidance, which helps the agent formulate effective queries.

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

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

The description clearly states that the tool routes questions to 5,529 tools across verified sources and returns structured answers with pipeworx:// citation URIs. It also distinguishes itself from sibling tools by naming ask_pipeworx_grounded and deep_research as alternatives for specific cases.

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 'PREFER OVER WEB SEARCH' and 'START HERE for most questions', provides trigger phrases and examples, and gives concrete guidance on when to step up to ask_pipeworx_grounded or deep_research. This gives the agent clear decision boundaries.

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

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

Annotations already declare read-only, open-world, idempotent, and non-destructive hints. The description adds valuable context about the beta nature: candidate routing improvements are enabled live only during tests, no candidate is currently active, and it's a full working router. This goes beyond the annotations to explain the experimental edge and comparison process.

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

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

The description is somewhat long but each sentence provides essential information: what it is, current state, when to use, and comparison behavior. It is front-loaded with the core definition and avoids unnecessary fluff, 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 complete operational context: it's a beta of ask_pipeworx, has the same tool/argument/response shape, is currently identical to the stable version, and is used for testing routing improvements. Even without an output schema, referencing the same response shape as ask_pipeworx is sufficient. The comparison mechanism is also disclosed.

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 six parameters being aliases for 'question'. The description merely mentions 'same arguments' without adding new meaning beyond the schema. Since the schema fully documents the parameters, 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 defines the tool as a beta version of ask_pipeworx, an identical universal router with candidate routing improvements. It distinguishes itself from the stable ask_pipeworx by highlighting its experimental edge and current matching behavior, making its 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?

Explicit guidance is provided: 'Use it exactly like ask_pipeworx when you want the newest routing' and results are compared against the stable router. This clearly states when to use the beta versus the stable alternative, fulfilling the dimension's requirements.

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, idempotent, non-destructive), the description discloses the detailed refusal mechanism with specific refusal_reason values, the structured output format, and the cost of one extra LLM call. It also states that answers are extracted using ONLY the tool result, which is critical behavioral context for an agent deciding whether to trust output.

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

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

The description is dense but each sentence serves a purpose: it establishes the tool's unique value proposition, explains the mechanism, details the return/refusal formats, gives concrete usage guidance, and names the tradeoff vs. the sibling tool. No filler or redundant repetition.

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

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

Despite lacking an output schema, the description fully defines the success and refusal response shapes, including all possible refusal_reason values. It covers the tool's operational context (routing, source count), cost, and appropriate use cases, making it sufficiently complete for an agent to decide when and how to 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?

The input schema already documents all 6 parameters with 100% coverage, describing each as an alias for 'question'. The tool description adds no further parameter-level detail, so it relies on the schema's adequate coverage. Baseline 3 is appropriate.

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

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

The description clearly identifies the tool as a 'Hallucination-resistant answer mode for high-stakes reads' and explains the process: routing, fetching data, and extracting answers only from tool results. It explicitly contrasts with ask_pipeworx while sharing the same routing, making the distinction from siblings clear.

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 use cases: 'Use whenever an answer will be quoted, cited, or acted on, and the agent must not invent facts' with concrete examples. It also provides a clear when-not-to-use: 'prefer ask_pipeworx for casual lookups' due to the extra LLM call cost, directly naming the alternative.

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

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

Annotations already mark readOnlyHint=true and openWorldHint=true. The description adds extensive behavioral details: market resolution, fan-out mechanism, response shapes, resolver contract (match confidence, alternatives), parent event extractor, news fallback fields, safety short-circuits, closed market handling, and resolution-rule risk. No contradiction with annotations.

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

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

The description is very long and covers many technical details (fan-out examples, response shapes, resolver contract). While front-loaded with purpose and usage, the density of information could benefit from bullet points or clearer sectioning. It is exhaustive but not 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?

Given the tool's complexity (classifiers, fan-out, response fields, edge cases), the description is remarkably complete. It covers input variations, output structure, error/safety paths, resolution-rule risk, and blocking conditions. No output schema exists, but response shapes are detailed.

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

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

Schema coverage is 100%, so baseline is 3. The description adds extra meaning: explains depth enum (quick=2-3 sources), market input types (slug/URL/text), and include_raw with detailed rationale (response size trade-offs). This enriches understanding beyond raw 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 researches a Polymarket bet by pulling Pipeworx data. It specifies the action (research), resource (bet), and input types (slug, URL, question text). The detailed classifier list and fan-out examples distinguish 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?

The description explicitly says 'Use for "should I bet on X", "what does the data say about Y", or "is there edge in Z"', providing clear context. It does not explicitly exclude alternatives, but sibling tool names are provided, allowing the agent to differentiate.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds significant behavioral context: data sources (SEC EDGAR/XBRL for companies, FAERS for drugs), handling of off-calendar fiscal years, sorting by primary metric, and citation URIs. No contradiction.

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

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

The description is relatively long but well-structured with front-loaded examples and clear sections. Every sentence adds value, though it could be slightly more concise without losing essential details.

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

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

Given the tool's complexity (two entity types, different data sources) and no output schema, the description is thoroughly complete. It explains return data, sorting, and the advantage over sequential lookups, fully compensating for absence of 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% with both parameters described. The description adds meaning beyond schema: for type='company', it specifies financial metrics (revenue, net income, cash, long-term debt); for type='drug', it specifies FAERS data, FDA approvals, and trial counts. Also clarifies array constraints (2-5 items).

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

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

The description clearly states the tool performs side-by-side comparison of 2-5 companies or drugs, using example queries like 'compare X and Y' and 'head to head'. It distinguishes from siblings like entity_profile (single entity) and sequential lookups.

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

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

The description explicitly says 'ALWAYS PREFER over sequential single-pack lookups' and gives guidance on when to use each type (company or drug). It lacks explicit when-not-to-use scenarios but provides strong usage context.

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

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

Although annotations already declare readOnly/openWorld/idempotent, the description adds extensive behavioral context beyond annotations: account requirements, parallel facet routing, return packet structure (verbatim evidence, confidence, gaps[], contradictions[]), citation_uri resolvability, hop field, semantic excerpting, and expected latency ranges. It also explicitly states the tool 'never invented' answers, a critical trust signal.

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 each sentence adds essential information for a complex tool, from auth prerequisites to output semantics to latency expectations. It is front-loaded with the account requirement and core purpose, then systematically covers usage, behavior, and return details. Dense yet well-organized, though slightly overlong for quick scanning.

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 findings packet, gaps[], contradictions[], citation_uri, hop, and semantic excerpting—so an agent knows exactly what to expect. It also covers operational caveats (account tiers, latency, news-only limitations) and how multi-step questions resolve in one call, making the description complete for this complex tool.

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

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

Schema description coverage is 100%, with both `question` and `depth` already well-documented in the input schema. The description's details about depth behaviors (e.g., 'standard' re-angles gaps, 'thorough' chases leads) largely mirror the schema enum descriptions, adding only the paid-plan constraint for 'thorough'—useful but not core parameter semantics. Thus baseline 3 is appropriate.

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

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

The description clearly states a specific verb+resource: 'Grounded multi-source research across Pipeworx's 1455 STRUCTURED data sources' and explains the decomposition-and-parallel-routing mechanism, distinguishing it from siblings like ask_pipeworx. It explicitly contrasts with open-web search and single-lookup tools, making the tool's unique role 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: 'Best for broad/multi-part questions over structured data' and directly names alternatives: 'For a single lookup use ask_pipeworx' and 'For BREAKING or colloquial CURRENT-NEWS... prefer ask_pipeworx'. It also provides account-tier prerequisites and fallback instructions for non-signed-in users, making selection criteria very clear.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: returns top-N tools with full schemas and examples, ready to call without a second lookup. No contradictions.

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

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

The description is front-loaded with a clear purpose and usage, but the list of domains is lengthy. Every sentence earns its place, though it could be slightly more concise. Still well-structured and informative.

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 main input) and no output schema, the description covers all necessary context: what it returns (tools with names, descriptions, schemas, examples), how many (top-N), and that they are ready to call. Complete for the use case.

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 6 parameters. The description does not add significant meaning beyond the schema, except listing example queries. Baseline of 3 is appropriate since the schema already documents parameters adequately.

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: to find/discover tools by describing data or tasks. It lists many specific domains (SEC filings, financials, FDA drugs, etc.) and uses a specific verb 'Find tools', distinguishing it from sibling tools which are diverse and not metatools.

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 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'. This provides clear context for when to use. It does not explicitly state when not to use, but the guidance is strong enough for a score of 4.

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

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

Annotations already indicate read-only, open-world, idempotent, non-destructive behavior. The description adds details about data sources, handling of patent soft-fails, and that names are not supported. It does not contradict annotations.

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

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

The description is dense with information but front-loaded with example queries. It could be more structured (e.g., bullet points), but every sentence adds value. Slight deduction for lack of clear sectioning.

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

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

Given no output schema, the description lists return fields and data sources comprehensively. It covers key aspects of what the tool returns. Could mention error handling or edge cases, but sufficient for the 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?

Both parameters are described in the schema (100% coverage). The description adds context: value can be ticker or CIK, type only 'company', and names not supported. This adds meaningful guidance 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 specifies the exact purpose: returning a full cross-source profile of a US public company. It lists specific data sources and fields, and distinguishes from sibling tools like '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 explicitly says to prefer this tool over chaining single-pack lookups for holistic views, and notes when to use 'resolve_entity' first if only a name is available. It also provides example queries.

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

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

The description confirms the destructive action (delete), aligning with annotations (destructiveHint=true, idempotentHint=true). It does not add new behavioral details beyond what annotations provide, but does not contradict them.

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

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

Two sentences, front-loaded with the core action. Every sentence adds value 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?

For a simple one-parameter destructive tool, the description covers purpose, usage context, and relationships. No output schema needed; it is complete for agent understanding.

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

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

Schema coverage is 100%, so the parameter 'key' is fully described in the schema. The description mentions 'by key' but adds no additional meaning or constraints 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 'Delete a previously stored memory by key,' which is a specific verb+resource combination. It distinguishes from sibling tools 'remember' and 'recall' by focusing on deletion.

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

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

Provides explicit when-to-use scenarios: 'context is stale, task is done, clear sensitive data,' and suggests pairing with 'remember' and 'recall,' offering clear guidance on alternatives.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is clear. The description adds behavioral detail: 'Fetches the page, extracts title/description/key links, and emits the standard llms.txt markdown format', which goes beyond annotations.

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

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

The description is three sentences: purpose, process, use cases. Efficient and well-front-loaded; every sentence adds value.

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

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

Given simple tool (2 params, no output schema), the description covers what it does, how it works, and when to use it. Output is described as a 'text blob' in markdown format, which is sufficient. Minor gap: no error handling or page size limits.

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

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

Schema coverage is 100% with both parameters described. The description adds marginal context (e.g., 'Full URL' is already in schema, 'maximum number of link entries' mirrors schema). Baseline 3 is appropriate; no significant extra meaning.

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

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

The description clearly states the verb 'Generate' and the resource 'production-ready llms.txt file for any URL', specifying the purpose for AI crawlers. It also distinguishes from sibling tools like 'ai_visibility_check' by focusing on file generation.

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

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

The description explicitly lists three use cases (getting a client's site indexed, drafting for own project, auditing competitor). While it doesn't mention when not to use or alternatives, the use cases provide clear context.

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

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

Annotations already provide readOnlyHint, idempotentHint, destructiveHint=false. Description adds what fields are returned and the effect of the optional parameter. No contradiction.

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

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

Two sentences, front-loaded with action and key info. No fluff.

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

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

With no output schema, description lists return fields. Parameter optional and documented in schema. Annotations cover safety. Complete for a simple list 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 parameter description. Description does not add meaning beyond schema, but schema fully documents the parameter. Baseline 3 appropriate.

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

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

Description clearly states it lists the caller's active subscriptions and specifies return fields. Distinguishes from siblings like subscribe/unsubscribe by implying it's for review or finding IDs.

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

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

Explicitly says 'Use this to review what you're monitoring before adding more or to find an id to cancel.' Provides clear context for when to use, though no 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 annotations, the description discloses important behavioral details: rate limiting ('Rate-limited to 5 per identifier per day'), the claim_token workflow ('Filing without an account returns a claim_token; pass it back later...'), cost implications ('Free; doesn't count against your tool-call quota'), and the fact that reports are read daily and influence roadmap. No contradictions with annotations.

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

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

The description is long but every sentence serves a distinct purpose: core purpose, when to use, scope exclusions, message guidelines, token workflow, rate limits, and cost. It is front-loaded with the main purpose and structured logically. Slightly verbose, but the complexity (multi-purpose, exclusions, two-phase token) justifies the length.

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

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

Given there is no output schema, the description adequately explains the return behavior (claim_token and later status updates). It covers the tool's full lifecycle, including exclusions, rate limits, and practical tips. For a feedback tool with a complex token mechanism and clear differentiation among 30+ siblings, the description is complete and self-sufficient.

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

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

Schema coverage is 100%, so the schema already documents all parameters. However, the description adds practical meaning: it explains the claim_token's revisit syntax ('pass it back later as pipeworx_feedback({claim_token:"pwfb_…"})'), specifies that claim_token should be used with no other arguments, and advises on message content ('Describe the issue in terms of Pipeworx tools/packs — don't paste the end-user's prompt'). This goes beyond the schema's dry 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: 'Tell the Pipeworx team something is broken, missing, or needs to exist.' This uses a specific verb and resource (feedback for Pipeworx tools), and it is distinct from sibling tools which are all research/query-oriented. The differentiation from siblings is further reinforced by the explicit scope of 'tools served by this Pipeworx connection.'

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

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

The description provides explicit when-to-use guidance: '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 clearly states when NOT to use it: 'if the tool came from a different MCP server in your client... file it with that server instead.' This is exemplary usage guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false. Description adds critical behavioral details: data source (CF analytics-engine), privacy (no PII), and caching (5min-1h). No contradictions.

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

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

Single paragraph is information-dense with a clear overview and bullet-pointed use cases. Could be slightly more concise, but every sentence adds value.

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

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

No output schema, but description adequately covers inputs, data source, and caching. Omits exact return format, but the tool is simple and return types are implied. Still very complete for the 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% (window parameter described). Description adds meaningful context: shorter windows for hot trends, longer for steady-state demand, enhancing the schema's enum explanation.

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

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

Description clearly states the tool returns top tools, top packs, and total call volume over a recent window. It uses specific verbs and resources, distinguishing it from siblings like discover_tools and 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?

Provides three explicit use cases (discovering hot data, confirming canonical tools, checking alignment). While it lacks explicit exclusions or alternative tool references, the context is clear and actionable.

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

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

Annotations indicate readOnlyHint, idempotentHint, and destructiveHint false. The description adds extensive behavioral context: explains arbitrage detection logic, output structure, fill check, semantic anchor, partition filter, and references to other tools. 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 detailed and well-structured, with front-loaded purpose and clear separation of modes. It is relatively long (about 300 words) but every sentence adds value. Slightly verbose but not overly so.

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

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

Given the tool has 2 optional parameters and no output schema, the description provides complete context: input modes, output format (opportunities array, partition check, fill check), edge cases (partition filter, low similarity), and references to related tools. No gaps.

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

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

Schema coverage is 100% with both parameters described. The description adds significant meaning: explains event slug and full URL acceptance, topic as a seed question, and the behavior of each mode. This goes beyond the schema descriptions.

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

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

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

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

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

The description provides clear guidance on when to use each mode: no args for trending scan, 'event' for specific market, 'topic' for cross-event scanning. It explains the benefits of cross-event mode and recommends 'event' for specific markets. However, it does not explicitly state when not to use this tool versus other sibling tools.

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

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

Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds extensive detail on model families (crypto_price, news_momentum, partition_overround, concentrated_longshot), edge calculation, Kelly sizing, and caching behavior (1h at KV level). No contradictions with annotations.

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

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

The description is front-loaded with a clear purpose and well-organized into sections (model families, response fields, knobs). It is verbose but every sentence adds value, explaining complex components succinctly. Minor redundancy could be trimmed, but overall efficient.

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

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

Despite no output schema, the description thoroughly explains the response structure, including by_segment segments, fields like edge_pp_net and kelly_fraction, diagnostic info (_diagnostics), and special notes on Fed bets. It covers edge cases and provides enough detail for an agent 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?

Schema coverage is 100% with descriptions for all 9 parameters, meeting the baseline of 3. The description adds extra context for parameters like slippage_pp (zero fees, typical bid/ask) and min_partition_leg_kelly (why min_kelly doesn't apply), enhancing understanding beyond the schema.

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

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

The description clearly states it scans Polymarket markets to find opportunities where Pipeworx data disagrees with market price, targeting 'what should I bet on today'. It distinguishes itself from siblings like polymarket_arbitrage and polymarket_edge_tracker by specifying its unique data source and methodology.

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 (discovering opportunities without paging hundreds of markets) and details internal knobs like min_liquidity and max_spread_pp. However, it does not explicitly contrast with sibling tools or state when not to use it, which limits its score.

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

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

The description adds significant behavioral context beyond annotations: it explains the response structure (tracked, expired, snapshot_dates), computation of trend and decay, and limits (60-day TTL, snapshot gaps). No contradiction with annotations.

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

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

The description is well-structured with ARGS and RESPONSE sections, front-loading the core purpose. It is verbose but every sentence adds value, making it informative without unnecessary fluff.

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

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

Given the absence of an output schema, the description thoroughly explains the response structure (three arrays) and covers all relevant aspects: parameters, behavior, limits, and data interpretation. It is complete for effective tool use.

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

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

The input schema already covers both parameters with descriptions, and the description adds default values (days=14, clamp 2-30; window='1wk') and explains the role of 'window' as snapshot family. This adds meaningful context beyond the schema.

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

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

The description clearly defines the tool's purpose: providing edge persistence and decay telemetry from daily snapshots. It distinguishes itself from sibling tools like 'polymarket_edges' by focusing on historical time-series and decay metrics.

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

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

The description implies when to use the tool (to analyze edge longevity) and contrasts with fresh edges. However, it does not explicitly state when not to use it or mention alternative tools beyond implication.

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, idempotent, not destructive), the description reveals tool behavior: walks order book ladder, returns top_of_book, vwap_fill_price, slippage, verdict, forced directional risk in basket mode. It warns about partial fills converting arb to unhedged position. No contradiction with annotations.

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

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

The description is well-structured with clear mode labels and front-loaded summary. Every sentence adds value, though it is somewhat lengthy. Could be slightly more concise but justified given complexity.

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

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

Given the tool's complexity (two modes, 4 params, no output schema), the description is very complete: explains return values, warnings, and usage context. No gaps identified.

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

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

Schema coverage is 100%, but description adds significant meaning: explains size_usd interpretation for single-market vs basket, default side logic in basket (auto from partition sum), clamp range (10–1,000,000), and mutual exclusivity of market and event. This goes well beyond schema.

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

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

The description clearly states it performs a 'Realizable-vs-theoretical edge check against live CLOB order-book depth' and distinguishes two modes (single-market and basket). It explicitly differentiates from sibling tools by specifying to use this before acting on polymarket_arbitrage signals or polymarket_edges trades above ~$500.

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 ('USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500') and explains why (theoretical overround not capturable, partial fills create unhedged positions). It also clarifies that one of market or event is required and provides defaults.

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

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

Annotations indicate read-only, idempotent, non-destructive. Description adds extensive behavioral context: compatibility warnings, temporal alignment, skipped cross-type/subtype counters, and the caveat that most pre-mapped topics return warnings.

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

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

Description is somewhat verbose but well-structured with clear sections (TWO MODES, RESPONSE, SAFETY FIELDS). Front-loads core purpose; every sentence adds value. Could be more concise but organized.

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

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

Complete coverage for a complex tool: explains response fields (leg prices, spreads, compatibility_warning, temporal_alignment, skipped counters) and warns about pitfalls. No output schema, but description suffices.

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 three parameters. Description adds context (examples, mode explanation) but does not significantly extend meaning beyond schema.

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

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

Description clearly states it computes cross-venue spread between Kalshi and Polymarket, distinguishes from siblings by focusing on venue arbitrage, and specifies two modes (topic shortcuts and explicit tickers).

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 detailed guidance on when to use each mode, warns that pre-mapped topics may not yield tradeable spreads, and explains limitations. Does not explicitly compare to sibling tools but context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. Description adds source context (MLIT) and listing purpose, but no additional behavioral traits like pagination or rate limits. No contradictions.

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

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

Two sentences front-loaded with purpose and usage. Every sentence adds value with no redundancy or filler.

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

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

Given the simple tool (2 params, no output schema, rich annotations), description fully covers purpose, input, and use case linkage to sibling. No gaps.

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

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

Schema description coverage is 100%. Description adds value beyond schema: clarifies _apiKey is optional with shared key fallback, and prefecture can be name or 2-digit code (01-47). Includes example in schema examples.

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?

Specific verb+resource ('List the cities/wards...and their 5-digit municipality codes') with concrete use case (resolve city code for realestate_transactions). Distinguishes clearly from sibling tool realestate_transactions by explaining its role as a helper.

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 to resolve a city code for realestate_transactions'. Describes accepted input formats (prefecture name or 2-digit code). Lacks direct mention of when not to use, but context is clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive. The description adds relevant behavioral details: coverage start dates, price types (transaction vs. agreed), and return fields. No contradiction. It does not disclose rate limits or pagination specifics, but the annotations carry 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?

Five well-structured sentences, front-loaded with the core purpose and immediate preference advice. Every sentence adds distinct value (source, preference, filters, coverage, return fields). No fluff or redundancy.

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

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

Given 8 parameters and no output schema, the description provides a strong overview of input filtering and return fields (type, district, price, area, etc.). It could mention output formatting or pagination default (limit 50), but the schema already specifies max 200. Overall, it equips the agent to use the tool effectively.

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 each parameter documented. The description adds context beyond the schema: e.g., 'year: transactions 2005+; agreed prices 2021+', and explains the relationship between prefecture/city/station filters. It also introduces the 'price_type' parameter meaning in prose. This adds meaningful value without being redundant.

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

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

The description clearly states the resource (Japanese real-estate transaction prices from MLIT), specifies the time frame (2005-Q3 onward, agreed prices 2021-Q1 onward), and identifies the action (query by prefecture/city/station, year, quarter, price type). It distinguishes from sibling tools like 'realestate_municipalities' and general web search.

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

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

The description explicitly advises to 'PREFER OVER WEB SEARCH' for Japanese property/land prices, housing market data, etc. It lists concrete use cases (e.g., 'property/land prices in Tokyo/Osaka/<Japanese city>') and specifies filtering options. While it doesn't explicitly state when not to use, the positive guidance is strong enough.

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

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

Annotations confirm readOnlyHint, description adds useful context: scoping per identifier, listing all keys when omitted, pairing with remember/forget. No contradictions.

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

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

Two sentences, front-loaded with action, no redundancy. Every sentence adds value.

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

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

Low complexity tool with 1 optional param. Description covers retrieval, listing, scoping, and sibling relationships. Complete for correct 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 covers 100% of parameter. Description adds no new detail beyond schema, but baseline 3 is appropriate.

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

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

Description uses specific verbs 'Retrieve' and 'list', identifies resource as values saved via remember, and distinguishes from siblings remember and forget.

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

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

Explicitly states when to use: to look up stored context without re-deriving. Provides scoping info and pairing with remember/forget. No negative 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 indicate read-only, idempotent, non-destructive. Description adds behavior on mark_read flag and returned field details, which supplements the annotations without contradiction.

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

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

Concise three-sentence description that efficiently conveys purpose, parameters, and usage notes without redundant information.

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

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

No output schema, but description adequately describes return fields and parameter behaviors. Covers all necessary aspects for a retrieval 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 has 100% coverage, but description provides useful examples (e.g., 'sec_8k' for type) and clarifies the effect of mark_read on subsequent calls, adding value beyond schema.

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

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

The description clearly states it pulls fired events from the subscription feed, with specific details on returned fields (source, citation_uri, raw payload). No sibling tool has identical function.

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

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

Explains how polling works and mentions an alternative HTTP endpoint for scripts/dashboards. Does not explicitly exclude scenarios but gives sufficient context for correct usage.

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

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

Beyond annotations (readOnlyHint, etc.), it details parallel calling, data sources (SEC, GDELT/GNews, USPTO) with fallback and soft-fail conditions, and return structure including citation URIs. No contradictions.

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

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

Every sentence adds value, structured efficiently: queries, function, sources, parameter usage, return, alternative. No fluff, information-dense yet clear.

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

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

No output schema, but description adequately explains return format (changes grouped by source, total count, citation URIs). Covers parameter formats, source behaviors, and alternative tool for static data. Complete for the tool's complexity.

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

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

Schema coverage is 100%, so baseline is 3. The description adds practical examples for 'since' (ISO date, relative shorthand, typical values) and 'value' (ticker or CIK). This extra context elevates it 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 clearly defines the tool as a change feed for companies over a time window, with specific query examples. It distinguishes itself from the sibling tool 'entity_profile' by explicitly stating when to use the alternative.

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

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

Provides explicit query patterns, explains when to use (recent changes over a period), and specifies when not to use (static profile needs via entity_profile). Also describes fallback behavior between GDELT and GNews.

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 (which indicate a write operation with idempotency and no destructiveness), the description discloses scoping by identifier, persistence duration (24 hours for anonymous, permanent for authenticated), and that it stores key-value pairs.

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

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

Three sentences, each serving a clear purpose: stating the function, giving usage guidance, and detailing behavior. No redundant 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?

For a two-parameter tool with no output schema, the description covers purpose, usage, persistence, and pairing with siblings. It fully addresses the agent's needs for correct invocation.

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

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

Schema coverage is 100% with descriptions. The description adds value by providing concrete examples for the key parameter and clarifying the value as 'any text', which aids understanding beyond the schema.

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

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

The description uses a specific verb ('Save') and resource ('data'), and clearly states the scope ('across this conversation or across sessions'). It distinguishes from sibling tools by naming 'recall' 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?

Explicitly says when to use: 'when you discover something worth carrying forward'. It also provides context for when not to overuse by implying it's for persistent storage, and mentions alternative tools ('recall', 'forget').

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 richly discloses behavior beyond the read-only/idempotent annotations: graceful degradation when GLEIF or OpenFIGI is unavailable, internal cascading through multiple endpoints, source-labeling of identifiers, and explicit reporting of unresolved identifiers. This adds significant context not contained in the annotations.

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

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

The description is long but well-structured, using example queries, clear type breakdowns, and fallback notes. It is mostly efficient, though some information (e.g., 'accepts ticker, CIK, or company name') duplicates the schema, causing minor 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?

Even without an output schema, the description covers the key return aspects: identifiers (CIK, ticker, LEI, FIGI, RxCUI), source provenance, unresolved-handling, and degradation behavior. For a tool with this complexity, the description 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?

Schema coverage is 100%, but the description adds substantial meaning for the 'type' parameter by detailing what each entity type returns (company vs drug). It also reinforces the 'value' input formats. Since the description goes beyond the schema's basic descriptions, it earns above-baseline.

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

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

The description precisely defines the tool's role as resolving user-spoken names to canonical identifiers, with explicit example queries and supported types. It distinguishes itself from sibling tools by stating '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 provides clear guidance on 'when' to use the tool ('Use FIRST whenever you have a name but need an ID') and gives indicative query patterns. However, it does not explicitly name alternative tools for cases where an ID is already known, so it lacks a full when/when-not comparison.

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

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

Annotations already declare readOnly and idempotent. Description adds that it calls ai_visibility_check internally, ranks results, and returns list with score, confidence, signal density. No contradictions.

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

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

Three short sentences, front-loaded with main action. Every sentence earns its place: purpose, mechanism with use case, output description. No unnecessary words.

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

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

Given no output schema, description adequately explains output format. Covers key aspects: ranked list, score, confidence, signal density. Does not cover error cases but overall sufficient.

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

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

Schema has 100% description coverage. Description adds meaningful context: first entity treated as subject, competitors for comparison. Clarifies models parameter with instruction to omit for default.

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 'Compare AI visibility' and resource 'multiple entities side-by-side'. Clearly distinguishes from sibling tool ai_visibility_check by stating it probes each entity with that tool and ranks them.

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

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

Provides concrete use case for competitive AI-marketing audits. Implies single entity checks should use ai_visibility_check. Could explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds valuable behavioral details: fans out to external services, partial failures with graceful degradation, and potential 5-30s delay for bundlephobia. Could mention rate limits or failure modes more precisely, but overall strong.

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

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

The description is detailed but efficiently organized: starts with the core purpose, then usage, then return structure, and edge cases. Each sentence adds value. Slightly long but justified by the complexity.

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

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

Despite no output schema, the description comprehensively lists all return fields, including summary block details, advisories, links, and alternatives. Also covers ecosystem scope, version handling, and partial failures. Complete for agent understanding.

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

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

Schema coverage is 100%, with descriptions for both parameters. The description adds minor context (accepts scoped packages, version defaults to latest) but does not significantly enhance understanding beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the tool's purpose: a composite check for evaluating npm packages using deps.dev and bundlephobia. It specifies the exact scenario ('should I add this npm package') and distinguishes from siblings by focusing on npm ecosystem only.

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: 'whenever an agent asks "is X safe / popular / small" or "what does adding lodash cost me". Also clarifies when not to use (other ecosystems) and directs to alternative (deps.dev:version).

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

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

Adds significant behavioral context beyond annotations: truncation at 200K chars with flag, embedding model (BGE-base-en), window size (500-char overlapping), cosine similarity, and offsets for verification. Annotations cover safety (readOnly, idempotent); description enriches technical 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?

Compact yet comprehensive: first sentence states purpose, second gives usage scene, third provides technical internals. No redundant phrases; every sentence earns its place.

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

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

Despite no output schema, the description explains return format (passages with offsets and scores), cap and truncation behavior, and technical basis. All user-facing behavior is covered.

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

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

Schema coverage is 100%, so baseline is 3. Description adds value: example queries for 'query', default value for 'limit', and reiterates the truncation cap for 'text'. This goes beyond the schema descriptions.

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

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

The description uses specific verb+resource ('Semantic search INSIDE a fetched record'), gives concrete examples (SEC 10-K, article), and distinguishes itself by mentioning a sibling tool (ask_pipeworx_grounded) and the offset feature.

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

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

Explicitly states when to use: 'Use when the record is too big to cram into the prompt', explains context savings, and pairs with ask_pipeworx_grounded. Lacks explicit when-not-to-use but provides clear context.

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

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

Annotations indicate a write operation (readOnlyHint=false), and the description adds critical transparency: account requirements, delivery constraints (phone verification, SMS cap), webhook auto-disable after 10 failures, and the fact that anonymous/BYO cannot persist subscriptions. No contradictions with annotations.

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

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

The description is well-structured and front-loaded with the purpose, then types, then channels. It is slightly lengthy but every sentence adds value (details on types, constraints, verification). Could be trimmed slightly but remains effective.

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

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

Given no output schema, the description covers the return value ('Returns the new subscription id'), constraints for each parameter, and edge cases like webhook auto-disable. It fully addresses the complexity of 3 params, nested objects, and multiple subscription types.

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

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

Schema coverage is 100%, and the description significantly adds meaning beyond the schema by detailing type-specific param structures, delivery channel formats (E.164 for SMS, email validation, webhook HMAC signing), and required fields like sponsor or condition for clinical_trial.

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

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

The description clearly states the tool's verb ('Create'), resource ('proactive monitoring subscription'), and scope ('live-data event stream'). It distinguishes from sibling tools like list_subscriptions, unsubscribe, and recent_alerts by specifying the subscription creation purpose and requiring a Pipeworx OAuth account.

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 context on when to use: requires a Pipeworx OAuth account, lists supported types with parameter examples, and explains delivery channels. However, it does not explicitly mention when not to use or compare to alternatives like list_subscriptions or unsubscribe, which would improve 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 safe, non-destructive, idempotent, and open-world hints. The description adds context about returning structured questions with tool shapes and the ability to filter by topic, enhancing understanding beyond the annotations.

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

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

The description is front-loaded with common questions and well-organized, but slightly verbose due to listing many categories and alternatives. Every sentence adds value, but could be tightened without loss.

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

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

Given no output schema, the description adequately explains the return format (category-bucketed example questions with tool+argument shape). It covers use case, arguments, and linkage to other tools, making it complete for an onboarding tool.

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

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

Schema covers 100% of parameters with a description of 'topic'. The description adds value by explaining the effect of omitting vs. providing topic (full spread vs. focus) and giving examples of valid topics, which goes beyond the schema.

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

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

The description clearly states the tool's purpose as the onboarding entry point for agents, provides alternative phrasings, and specifies that it returns category-bucketed example questions with tool arguments. It effectively distinguishes itself from siblings by positioning itself as the introductory tool.

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

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

Explicitly states to use this tool first when unfamiliar with Pipeworx, describes how to call with or without the topic parameter, and mentions learning about meta-tools. Provides clear when and how to use, though does not explicitly list when not to use.

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

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

Beyond annotations (idempotent, non-destructive), the description reveals that the row is deactivated, not deleted, and historical events remain available via recent_alerts. 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?

Two concise sentences, front-loaded with the primary action, no extraneous information.

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

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

For a simple one-parameter tool with no output schema, the description covers purpose, usage constraint, and behavioral impact completely.

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

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

Schema coverage is 100%. The description adds ownership context but does not elaborate on the parameter format or constraints beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Cancel a subscription') and specifies the resource ('by id'). It distinguishes itself from sibling tools like 'subscribe' and 'list_subscriptions'.

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

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

The description explicitly mentions ownership enforcement ('you can only cancel your own subscriptions'), providing essential usage context. It could mention when not to use it, but the constraint is clear.

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

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

Annotations already indicate read-only/idempotent/non-destructive, and the description adds important behavioral nuance: 'could_not_verify' means the check did not happen and must not be treated as evidence, while 'unsupported' means no source was found. It also discloses the routing logic (financial vs. other claims). This goes well beyond annotations without contradiction.

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

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

The description is dense and somewhat long, but every part serves a purpose: trigger examples, usage, internal routing, return values, and critical caveats. It uses semicolons and an 'IMPORTANT' callout for clarity. While not as tight as a two-sentence description, it avoids fluff and is 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?

There is no output schema, so the description must explain return values. It does so thoroughly: enumerates all verdict types, mentions the actual value with pipeworx:// citation and reasoning, and explains error semantics for could_not_verify and unsupported. This fully equips an agent to invoke and interpret the tool correctly.

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

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

Schema coverage is 100% with detailed descriptions for both `claim` and `tolerance_pct`. The description adds context about tolerance behavior ('exact percent-delta math' and default capped at 5) and clarifies how claims are routed, which enriches the parameter semantics beyond the schema. A high-coverage schema would baseline at 3, but the added context justifies 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 states a specific action: 'natural-language claim verification against authoritative sources', with trigger phrases and a clear outcome (verdict categories). It distinguishes itself from sibling ask/tool tools by focusing on fact-checking and returning a structured verdict. The examples of claim types further clarify scope.

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

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

Provides an explicit usage trigger: 'Use whenever the agent needs to check whether something a user said is factually correct.' It also notes the tool replaces 4–6 sequential calls, signaling when it is more efficient. 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.