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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description's trailing 'Stateless, read-only, idempotent' largely restates them. Where it adds real value is the payoff context ('reduce multimodal vision token consumption by up to 75%') and clarifying that the output is an ROI bounding box rather than a transformed image, though it omits the actual coordinate/format of the returned boxes.

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 tight sentences, front-loaded with the computation and its benefit before the usage constraint. The final 'Stateless, read-only, idempotent visual ROI analysis' clause is mild redundancy against the annotations rather than new information, so it is slightly less than optimal.

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, single-required-input tool with no output schema, the description covers purpose, usage, cost benefit, and safety profile adequately. It could say more about what the returned ROI data looks like (coordinates, count, single vs. multiple boxes), which is the one gap an agent might care about.

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 both parameters are already documented, including the enum values and the 'auto' default. The description names the same element categories but adds no syntax, format, or defaulting nuance beyond the schema, so it sits at the 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 gives a specific verb and resource ('Computes optimal Region-of-Interest bounding boxes') plus the target element categories, and explicitly differentiates itself from the adjacent screenshotting tool. An agent can select it over `topai_headless_screenshot` without opening either schema.

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

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

It states the positive trigger ('Use when preparing screenshots or document images for vision-capable LLMs'), the exclusion ('Do not use for taking the initial webpage screenshot'), and names the alternative (`topai_headless_screenshot` first). This is the full when/when-not/alternative triad.

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=false, destructiveHint=false, so the safety and world-model profile is covered. The description adds 'noise-free organic results' and 'stateless, read-only execution,' which reinforce but largely restate the annotations. No pagination, rate limit, latency, or freshness-window detail is added.

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

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

Four sentences, front-loaded with the purpose and result shape, then routing rules. Slightly verbose with the 'stateless, read-only execution' clause that duplicates annotations, but no wasted sentences.

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

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

Covers purpose, result contents, usage routing, and safety state for a simple 2-parameter read tool. No output schema, but the description names the return shape (titles, canonical URLs, snippets), which suffices. Lacks freshness/pagination hints but those are minor here.

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 query and max_results fully documented including bounds and default. The description adds no syntax, format, or operator guidance beyond the schema, so baseline 3 applies.

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

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

States a specific verb (executes a real-time web search query) and resource (organic results with titles, URLs, snippets), and explicitly distinguishes itself from two named siblings (topai_web_to_markdown, topai_google_ai_overview). An agent can route correctly without opening other schemas.

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

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

Provides explicit when-to-use (up-to-date external facts, news, URL discovery) and two explicit when-not-to-use clauses with named alternatives and the condition selecting each. This is textbook routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false. The description restates 'Stateless, read-only, idempotent query', which largely duplicates the annotations rather than adding new context. It does not add anything about result ordering, data freshness, or rate limits beyond the structured hints.

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

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

Three sentences, front-loaded with the core purpose, followed by usage guidance and the invocation contract. No filler, every clause earns its place.

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

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

For a 3-param read-only query tool with no output schema and full param documentation, the description is essentially complete: purpose, scope, alternative, and behavior are all present. The only minor gap is that it does not clarify output shape or sorting, which matters slightly without an output schema.

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

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

Schema description coverage is 100%, with each parameter including bounds and examples, so the baseline is 3. The description only summarizes that filtering is by industry, country, and limit, adding no syntax, format, or edge-case detail 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?

States a specific verb and resource ('Queries verified B2B company and executive lead records') and names the filter dimensions (industry vertical, ISO country code, result limit). It also explicitly distinguishes itself from the sibling enrichment 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?

Gives positive usage contexts (prospect lists, sales pipelines, market landscapes) and an explicit exclusion: when you have a specific domain needing technographic profiling, use topai_company_enrichment. Both when-to-use and when-not-to-use are covered with the named 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, and the description's 'Stateless, read-only, idempotent lookup' mostly restates them. The genuinely additive part is the enumeration of returned metadata, but there is no mention of auth requirements, rate limits, or behavior on unknown/missing domains — a real gap for an open-world external lookup.

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?

Purpose is front-loaded, followed by routing guidance, with no filler or marketing language. The final 'Stateless, read-only, idempotent lookup' sentence largely duplicates the annotations, which is the only wasted sentence.

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 usefully enumerates the returned field categories, and routing is fully covered. Minor gaps remain around return shape/coverage (e.g., what happens when enrichment finds nothing) for an open-world lookup, but it is sufficient to invoke correctly.

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

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

Schema coverage is 100% and the single parameter is fully documented in the schema, including an example ('linear.app'). The description's example domain duplicates the schema example and adds no format or constraint detail beyond it, so baseline 3 applies.

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

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

States a specific verb (enriches) and resource (a single corporate domain name), then enumerates the returned firmographic fields. It explicitly distinguishes itself from two sibling tools, so an agent can select it without opening any schema.

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?

Gives an explicit when-to-use condition ('you have a known company domain') and two when-not cases with named alternatives (`topai_b2b_data_leads` for discovery, `topai_techstack_fingerprint` for exhaustive fingerprinting). Routing is unambiguous.

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 return semantics the annotations do not carry (a 0.0–1.0 fraud risk score) and names the detection techniques. The closing 'Stateless, read-only, idempotent verification' largely restates the annotations, and 'DNS MX heuristics' sits in mild tension with openWorldHint=false since MX lookups are network-dependent — but this is a nuance, not a hard 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?

Front-loaded with the core purpose, then usage, then an exclusion, then a behavioral tagline — four efficient sentences. The final sentence duplicates annotation content and could be dropped 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?

No output schema exists, and the description fills that gap by stating the return value and its range. Combined with explicit usage/exclusion guidance and method disclosure, an agent has everything needed to select and invoke it correctly.

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

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

Only one parameter with 100% schema description coverage, so the schema already documents the email string, its format, and an example. The description adds no parameter-level detail beyond the schema, which is the expected baseline when coverage is complete.

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: 'Detects disposable, burner, or temporary email addresses', plus the detection methods (RFC 5322 parsing, throwaway domain blocklists, DNS MX heuristics) and the return value (fraud risk score 0.0–1.0). This clearly distinguishes it from siblings like topai_prompt_shield or topai_healthcare_validator.

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

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

Explicit when-to-use scenarios (user signup, B2B lead cleaning, KYC fraud prevention) and an explicit when-NOT-to-use case that names the alternative tool: 'Do not use for enriching corporate firmographics ... use topai_company_enrichment instead.' Full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so 'Stateless, read-only execution' largely restates structured data; the 'stateless' qualifier is the only genuinely additive bit. The description does not mention auth, rate limits, or failure modes. No output schema exists, so the enumerated return fields carry some behavioral weight, but the safety profile is already annotation-covered.

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

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

Three sentences, front-loaded with what is extracted, then usage, then the exclusion, then the safety note. Every sentence earns its place with no redundant preamble 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?

No output schema exists, and the description compensates by naming the three returned artifacts (synthesis text, cited URLs, organic SERP count), which is enough for a stateless read tool taking a single required query. Minor gaps remain around null/empty-result behavior and localization semantics, but the essentials are 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 all three parameters (query, country, language) already have descriptions including defaults ('us', 'en'). The description adds no syntax, format, or constraint detail beyond the schema, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb (Extracts) and resource (Google AI Overview), and enumerates the exact payload returned: synthesis text, cited source URLs, and organic SERP count. It also differentiates itself from the sibling topai_ai_web_search by name, so an agent can route without opening either schema.

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?

Gives explicit positive triggers (GEO audits, citation tracking, analyzing Google AI summaries) and an explicit exclusion with the alternative to use instead ('Do not use for general fast web search when AI Overview citation tracking is unnecessary (use topai_ai_web_search instead)'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, and the closing sentence largely restates those ('Stateless, read-only, idempotent'). The genuinely additive detail is the 'public webpage' constraint, which implies pages behind auth cannot be rendered, but this is not spelled out and no return-shape or failure behavior is described.

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

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

Three sentences, front-loaded with purpose then routing guidance, with no filler. The trailing 'Stateless, read-only, idempotent rendering' sentence is largely redundant with the annotations already attached to the tool, which is the only waste.

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 three-parameter read-only tool with no output schema, the description covers purpose, routing, and the public-URL constraint adequately. It does signal the return is metadata/dimensions rather than raw image bytes, but does not explain how a caller retrieves the actual image, leaving a modest gap.

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

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

Schema description coverage is 100%, so the schema already documents url, format, and full_page, including the enum values and defaults. The description only echoes the viewport/full-page distinction, adding no format, size, or URL-syntax detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('Renders a public webpage in a serverless headless browser') and names what it returns (viewport or full-page screenshot metadata and dimensions). It explicitly distinguishes itself from the sibling topai_web_to_markdown, so an agent can route correctly without opening either schema.

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?

Gives explicit when-to-use ('visual layout inspection, UI verification, or image capture of a live URL') and when-not-to-use ('only need the textual content') with the exact alternative named and a quantified reason (90% bandwidth/token savings). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the closing 'Stateless, read-only, idempotent verification' largely restates structured data and earns little. The description does add genuinely new context: the ISO Luhn 80840 checksum rule and the fact that license status and specialty metadata are returned, which matters because there is no output schema.

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

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

Front-loaded with the core action and algorithm, then usage, then the exclusion. The drug-patent exclusion is mildly tangential but functions as a real routing guard, so it earns its place; density is good with minimal waste.

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

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

With no output schema, the description compensates by stating what is returned (license status, specialty metadata) and how validation works. Combined with full schema coverage and existing annotations, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is 100%, so all three parameters are already documented at the schema level, and the description adds no param-level syntax or constraint beyond restating that the NPI is 10 digits. Baseline 3 applies; naming 'provider license status and specialty metadata' hints at output rather than parameter meaning.

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

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

States a specific verb and resource ('Validates 10-digit US National Provider Identifiers (NPI)') plus the exact algorithm used, and explicitly distinguishes itself from the closest sibling by naming topai_pharmapatent_watcher. An agent can select this tool without opening any schema.

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?

Gives explicit when-to-use scenarios ('verifying healthcare practitioners, medical facilities, or compliance onboarding records') and an explicit when-not with the alternative named. Both directions of routing are covered with no inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint and openWorldHint, so restating "read-only" and "idempotent" earns no credit. It does add "stateless" and, more usefully, enumerates the returned accounting fields, which compensates for the absent output schema. It omits failure behavior on malformed text, so it falls short of 5.

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

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

Three sentences, front-loaded with the purpose, then usage routing, then the trait tagline. Every sentence carries information, though the trailing "read-only, idempotent" clause partly duplicates annotation data and could be trimmed.

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?

Although no output schema exists, the description compensates by listing the extracted fields; with annotations covering the safety profile and the schema covering the single input, nothing an agent needs to select or call the tool is missing.

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

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

There is only one parameter and schema description coverage is 100%, with the schema itself documenting the raw-text input. The description reinforces it as "raw invoice text" but adds no format, size, or encoding detail 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?

States a specific verb (parses) and resource (unstructured invoice/receipt text) and enumerates the exact structured fields produced, so the agent knows precisely what comes out. It also names the sibling it is not (topai_math_fact_checker), making it distinguishable from the 17 other tools.

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

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

Explicitly gives the trigger condition ("Use when extracting structured financial data from OCR output or raw invoice text") and an exclusion with a named alternative ("Do not use for verifying mathematical VAT calculations... use topai_math_fact_checker instead"). Both when and when-not are covered.

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

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

Annotations already cover readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the 'Stateless, read-only, idempotent' clause largely repeats structured data. The description does add genuine behavioral context beyond the annotations: deterministic decimal/IEEE arithmetic and an 'explicit step-by-step audit trail' return characteristic. It does not cover failure modes or limits.

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 tightly-scoped sentences with the purpose and audit-trail behavior front-loaded, followed by usage routing. Minor waste in restating the annotation-covered 'Stateless, read-only, idempotent' traits, but nothing is padded.

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 does carry the burden of hinting at returns, and it does so via the 'step-by-step audit trail' phrase. All three operations and the upstream dependency on the extractor are covered, leaving only error/edge behavior unaddressed.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters including the operation enum and each field's role. The description adds no syntax, format, or constraint detail beyond what the schema provides, making the baseline 3 correct.

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

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

States a specific verb+resource ('Executes deterministic IEEE/decimal financial arithmetic') and enumerates the three concrete operations (VAT, invoice reconciliation, business-day counts). It also clearly differentiates from the sibling topai_invoice_extractor, so an agent can route correctly without opening any schema.

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

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

Explicit when-to-use ('whenever an agent must compute or verify taxes, invoice totals, or date intervals') and explicit when-not ('Do not use for parsing raw unstructured invoice text'), including the alternative tool and the correct sequencing ('use topai_invoice_extractor first, then pass extracted numbers here').

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 and openWorldHint=false, so the safety profile is fully covered structurally. The closing sentence 'Stateless, read-only, idempotent registry lookup' largely restates those annotations, with 'stateless' being the only genuinely additive trait. It adds some value but does not disclose pagination, result caps, or what a catalog entry contains.

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 doing a distinct job: what it does, when/when-not to use it, and its operational profile. Front-loaded with capability and routing guidance. The final sentence is partly redundant with the annotations, which is a minor deduction rather than a structural problem.

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 zero-required-parameter discovery tool with complete schema coverage and clean annotations, the routing information is sufficient. The one gap is that no output schema exists and the description never says what a lookup returns (e.g., tool names, descriptions, categories), which an agent choosing between discovery tools would benefit from knowing. Everything needed to invoke correctly is present, however.

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% for both optional parameters, so the schema already documents that `search` is a keyword substring match and `category` is a functional filter. The phrase 'by functional category or keyword' mirrors the schema without adding syntax, format, or matching-behavior detail (e.g., whether search is case-sensitive or how categories are enumerated). Baseline 3 applies when the schema does the heavy lifting.

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

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

States specific verbs (introspects, searches) and a precise resource (the TopAI Sovereign Gateway catalog of MCP tools), plus the axes of search (functional category or keyword). This distinguishes it cleanly from the domain siblings like topai_web_to_markdown or topai_healthcare_validator, which are the tools it discovers rather than being one of 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?

Explicitly says when to use it ('when an autonomous agent wants to discover which specialized tools are available... before selecting one') and when not to ('Do not use to execute a domain tool directly'), naming the alternative pattern (call the specific `topai_*` tool once identified). Both the positive trigger and the exclusion are stated, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so 'stateless, read-only, idempotent' largely restates structured data. However, the description adds genuine behavioral context beyond annotations: that it handles both internal and external $refs, neutralizes circular references, and yields a self-contained JSON document.

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

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

Three sentences, front-loaded with the core action, followed by usage routing and then a trait summary. The final clause mildly duplicates the annotation set, but overall the text is tight and well ordered.

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 exists, but the description discloses the return shape ('self-contained JSON document') and the transformation behavior, which is sufficient. Adding input format guidance (e.g., that exactly one of the two optional params is expected) would make it fully complete.

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

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

Schema description coverage is 100% and both parameters (spec_url, spec_json) are fully documented in the schema. The description adds no parameter-level syntax or format detail beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses specific verbs (dereferences, neutralizes, flattens) and names the exact resource (OpenAPI 3.0/3.1 specifications, internal and external $ref pointers). It explicitly distinguishes itself from the sibling topai_token_slimmer, so an agent can tell them apart without opening either schema.

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

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

It states the precise use case (before importing into RapidAPI, Postman, or LLM function-calling compilers that reject nested $ref pointers) and an explicit exclusion with a named alternative (not for JSON token minification, use topai_token_slimmer). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, and the closing line 'Stateless, read-only, idempotent lookup' largely restates them, earning no additional credit. The description does add data-provenance context (FDA Orange Book, European exclusivity), but says nothing about rate limits, auth requirements, or data freshness for an open-world external lookup.

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

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

Three sentences, front-loaded with the returned data, followed by usage scoping and the safety profile. Every sentence carries distinct information and there is no filler.

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

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

With no output schema, the description enumerates the return payload (cliff dates, ingredient metadata, exclusivity expirations, threat levels), so return semantics are covered. Inputs, exclusions, and safety profile are all present; nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the enum on jurisdiction is fully documented in the schema, so the baseline is 3. The description does not add format, defaulting, or matching semantics (e.g., brand vs. generic resolution) beyond what the schema already states.

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

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

States a specific verb (Retrieves) and a precisely scoped resource set: patent cliff dates, active ingredient metadata, Orange Book/EP exclusivity expirations, and generic entry threat levels for a named drug. This is clearly distinguishable from every sibling, and it even names the healthcare_validator it is not.

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 names the use cases (life-sciences competitive intelligence, LOE forecasting, pharma IP analysis) and gives an exclusion with a redirect: 'Do not use for verifying individual physician NPI medical licenses (use topai_healthcare_validator instead).' Both the when and the when-not are stated.

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

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

Annotations already declare readOnly, idempotent, and destructive=false, and the description largely restates these ('read-only, idempotent'). It adds only marginal new behavioral context ('Stateless') and doesn't discuss precision, rounding, or boundaries of the Kelly output — acceptable given a pure calculator but not rich.

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

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

Three sentences, front-loaded with the core computation, then usage, then the exclusion. No filler; every clause carries routing or scope 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?

With no output schema, the description usefully enumerates the return values (implied probability, mispricing delta, EV%, Kelly sizing), which is the key missing structured info an agent would need. It stops short of describing output format or edge-case handling, keeping it from a 5.

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

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

Schema description coverage is 100%, so each of the three parameters (including bankroll_usd and the 0.01–0.99 ranges) is already documented. The description connects bankroll to 'fractional Kelly criterion position sizing' but adds no format or edge-case detail beyond the schema, so baseline 3 applies.

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

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

The description uses a specific verb 'Computes' plus a precise resource set (implied probability, mispricing delta, EV%, fractional Kelly sizing) between two named inputs. An agent can distinguish this from every sibling, none of which are pricing/odds calculators.

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

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

It gives explicit when-to-use ('quantitative prediction market analysis, odds comparison, risk-adjusted bankroll allocation') and when-not ('Do not use for standard VAT or invoice accounting'), naming the alternative tool. Routing is fully specified.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds meaningful context beyond them: sub-millisecond latency, statelessness, and the return shape (boolean verdict plus 0.0-1.0 threat score). It does partially restate the read-only/idempotent traits that annotations already carry, which keeps it from a 5, but the added latency and return-format detail is genuinely useful.

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

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

Four tight sentences, front-loaded with the core action and threat list, then usage, then the anti-pattern with the alternative, then the behavioral/return summary. Every sentence earns its place with no 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?

Although there is no output schema, the description explicitly states what is returned (boolean safety verdict and a 0.0-1.0 threat score), and annotations cover the safety profile. An agent has everything needed to call this 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% and there is a single required parameter, so the schema fully documents the input. The description's mention of prompt/system-fragment/external-document text mirrors the schema description rather than adding new semantics; baseline 3 applies.

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

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

The description states a specific verb (scans) and resource (user prompts / untrusted external text) and enumerates the exact threats detected (prompt injections, jailbreaks, toxic payloads, PII leakage). It explicitly distinguishes itself from the sibling topai_token_slimmer, so an agent can route correctly without opening a schema.

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

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

It gives explicit when-to-use (pre-inference guardrail before passing untrusted input or scraped content to an LLM), when-not-to-use (compressing safe prompts), and names the alternative tool by name. Nothing is left to inference.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=false and readOnlyHint=false, so the safety profile is largely covered. The description nonetheless adds real context: the sub-5ms latency claim, the 'edge cache' deployment location, and which mode performs reads vs writes. It omits auth requirements, cache TTL/eviction behavior, and miss semantics, so it is strong but not exhaustive.

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

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

Front-loaded with the core action, then usage, then the sibling exclusion, with no filler sentences. The trailing 'Idempotent, non-destructive edge cache operation' partially restates what the annotations already carry, which is the only mild redundancy.

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

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

With full param coverage and annotations present, the definition covers purpose, usage, exclusion, and behavior adequately for a 3-param tool. Since there is no output schema, the one remaining gap is return semantics — what 'get' yields on a cache miss and what 'set' returns on success — but the 'check if an equivalent prompt was already answered' phrasing partially implies the hit/miss model.

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

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

Schema description coverage is 100%, so the schema already documents action, prompt, and response fully, including the get/set enum and the response-required-only-on-set constraint. The description restates the get/set duality without adding format or syntax detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb set ('get' lookups, 'set' storage) against a named resource (semantic vector cache for LLM prompts) with a concrete performance framing (sub-5ms). It also explicitly names the sibling it is not (topai_token_slimmer), so an agent can distinguish it without opening the schema.

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?

Gives explicit when-to-use instructions ('before invoking an expensive upstream LLM' to check for an equivalent prompt, 'right after generation' to cache the completion) and a concrete when-not with the alternative named ('compressing raw text... use topai_token_slimmer instead'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the closing 'read-only, idempotent' phrase largely restates structured data. The description does add genuine context though: '<50ms' latency, 'Stateless', and the signature count. It stops short of covering failure behavior (unknown domains), rate limits, or output shape, which keeps it at a solid but not rich 3.

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

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

Front-loaded with the core purpose and performance claim, then usage and exclusion, all in tight sentences. The trailing 'Stateless, read-only, idempotent inspection' fragment mildly duplicates the annotations, a minor waste in an otherwise efficient definition.

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 usefully implies the return content by enumerating the technology categories it reports. It is complete enough for a stateless single-input inspection tool, though it never states the output structure or error handling.

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

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

Schema description coverage is 100% and the single 'domain' parameter is already documented with examples ('gymshark.com', 'vercel.com'). The description adds no format or normalization guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('Fingerprints a web domain') with scope (70+ signatures) and enumerates what it identifies (CMS, e-commerce, analytics, CDN, frontend frameworks). It also names the sibling it is not for, letting an agent distinguish it from topai_company_enrichment without opening schemas.

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

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

Gives an explicit 'Use when' triggering condition, concrete detection examples (Shopify, Stripe, HubSpot, Next.js, Cloudflare), and a 'Do not use when' exclusion that routes to the specific alternative topai_company_enrichment. When/when-not/alternative are all present.

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

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

Annotations already cover readOnlyHint, idempotentHint and destructiveHint=false, yet the description adds genuinely new behavioral context: that compression is lossless and preserves semantic meaning, and that the tool is stateless. The trailing 'read-only, idempotent' phrasing largely restates the annotations, so it is not fully additive, but the lossless/stateless claim is real disclosure.

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 tightly packed sentences in a clear order: what it does and why, when to use it, when not to. No filler, no restating of the title, and the highest-value information (lossless 30-70% reduction) is front-loaded.

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

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

For a two-parameter tool with no output schema and full annotation coverage, the definition covers purpose, usage, exclusions and safety properties well. The one mild gap is the return shape — it never states that the output is the compressed payload string (or how the reduction is reported), which an agent must infer.

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

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

Schema description coverage is 100%, with both parameters documented including the format enum and its default. The description adds no syntax, size limits, or format-specific handling beyond what the schema already states (HTML/JSON/text is essentially the enum), so the baseline 3 applies.

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

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

States a specific verb (compresses) and resource (bloated HTML, JSON, or plain-text payloads), quantifies the benefit (30%-70% token reduction), and asserts the key property (lossless, semantics-preserving). It explicitly differentiates itself from topai_web_to_markdown and topai_semantic_cache, so an agent can distinguish it from siblings without opening the schema.

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?

Gives an explicit when-to-use trigger ('before sending large JSON API responses, logs, or RAG chunks into an LLM context window') and two explicit when-not-to-use cases that name the correct alternative sibling for each. This is exactly the routing guidance an agent needs.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so safety is covered; the description adds latency (<30ms), statelessness, and the fact that document metadata accompanies the output. It does repeat read-only/idempotent from the annotations, which caps it below the top band, but the timing and output-composition details are genuine additions.

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

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

Three sentences, front-loaded with the purpose before routing to alternatives, then a terse performance line. It is efficient, though the 'stateless, read-only, idempotent' clause partially restates the annotations.

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 stateless conversion tool with no output schema, the description covers purpose, alternatives, exclusions, latency, and the presence of document metadata. Only minor gaps remain (e.g., handling of non-HTML content or extraction failures), so it is nearly complete.

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

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

Schema coverage is 100% and both parameters carry full descriptions (URL validity/private-IP constraint, include_links default), so the schema does the heavy lifting. The description adds no parameter-level detail beyond that, which is the correct baseline of 3.

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

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

States a specific verb (converts), a precisely scoped resource (any public HTTP/HTTPS webpage), and the output form (clean, ad-free, token-optimized Markdown with metadata). An agent can distinguish it from every sibling without opening a schema.

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?

Gives explicit when-to-use context (reading article text, documentation, web pages before RAG indexing or summarization) and names two concrete alternatives with the conditions that select them: `topai_headless_screenshot` for pixel captures and `topai_ai_web_search` for keyword searches. Nothing is left to inference.

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