diogenes-neural-search-engine-mcp

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

Annotations already cover readOnly/idempotent/non-destructive, but the description goes further with concrete operational facts: stateless edge call, 32 KB payload cap, 60 RPM limit, demo mode, L402 payment of 15 sats, and HTTP 400 on invalid input. This is real behavioral value beyond the annotations, though it doesn't describe response content or partial-failure behavior.

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

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

The purpose and alternative routing are front-loaded, and the operational details are compressed into one sentence with no filler. It is dense and slightly technical, but each clause (limits, payment, error code) carries usable 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?

An output schema exists, so return-value detail is unnecessary; the description covers inputs, defaults, size/rate limits, payment requirements, and error signaling. For a stateless read-only call this is sufficient for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds extra meaning: it names text_or_headlines as the accepted input and supplies the default for sentiment_domain ('general_news'), which is not stated in the schema. It does not clarify entity_filter behavior, so it stops short of a 5.

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 (evaluates) applied to a concrete resource (sentiment across news headlines, discussions, articles) with an explicit output shape (bull/bear polarity scores). It also names the sibling it is not, so an agent can distinguish it from compile_competitive_landscape 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?

Explicitly gives use cases (market sentiment, social brand perception, controversy exposure on specific entities) and names the alternative tool plus the condition that selects it (competitive market comparisons). 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?

The description contradicts the openWorldHint=false annotation: it describes tracking breaking news feeds and external market catalysts, which inherently involve open-world external entities. Despite otherwise rich behavioral details (rate limit, payment, error codes), the direct contradiction with structured annotations forces a score of 1 per the rubric.

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 purpose, then usage guidance, then technical constraints. Every sentence adds value: the first defines the tool, the second routes the agent, and the third provides operational details (size limit, rate limit, payment, error behavior) without 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?

Given the output schema, complete parameter documentation, and annotations, the description fills all remaining gaps: it covers purpose, usage, alternatives, rate limits, authentication, size constraints, and error behavior. An agent can invoke the tool confidently based on this definition.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds useful semantics: it states the default for recency_window ('past_24_hours') and mentions '?demo=true' and L402 payment options not present in the schema. It does not elaborate on sentiment_cluster beyond the schema, keeping it from a 5.

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

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

The description states a specific verb and resource: tracks breaking news feeds, clusters trending story cycles, and calculates publication velocity. It explicitly names the sibling analyze_media_sentiment and distinguishes its own purpose from sentiment polarity evaluation.

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 conditions (breaking market catalysts, emerging controversies, product announcements) and names the alternative tool for sentiment analysis. 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false. The description adds real operational context beyond that: statelessness, 32 KB payload cap, 60 RPM rate limit, demo/L402 payment of 15 sats, and a 400 on invalid input. That said, it never describes what the response shape or error payloads look like beyond the status code, so it sits at a solid but not maximal level.

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 purpose before the exclusion and the operational parenthetical. Slightly dense with pricing/rate-limit details packed into one clause, but no sentence is wasted.

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 an output schema present, return values need no explanation. The description covers cost model, rate limit, size cap, default algorithm, error status, and the alternative tool — everything an agent needs to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds value by disclosing that clustering_method defaults to 'tf_idf_semantic_graph' and that the input is subject to a 32 KB limit, neither of which is in the schema. These are small but genuine clarifications beyond the structured data.

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: 'Discovers latent thematic clusters, subtopic branches, and conceptual relationships across document corpora.' It also names the sibling it is not for (summarize_temporal_timeline), so an agent can separate clustering from chronology 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 explicit use cases ('structuring broad search results into distinct thematic silos or generating table of contents taxonomies') and an explicit exclusion routing to summarize_temporal_timeline for chronological milestones. Nothing is left to inference about when to pick this tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantial context they don't carry: stateless edge call, 32 KB payload cap, 60 RPM rate limit, demo mode or L402 payment of 25 sats, and an HTTP 400 failure mode on invalid input. That is exactly the operational detail an agent needs before invoking.

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 and routing come first, with operational constraints trailing — good front-loading and no filler sentences. The final sentence is a dense run-on packing rate limits, payment, and error codes together, which slightly hurts scanability.

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

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

An output schema exists so return values need no explanation, and annotations cover the safety profile. Combined with the stated rate limits, size cap, payment path, and default framework, 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%, so baseline is 3; the description earns extra by disclosing the default value of 'analysis_framework' ('feature_and_pricing_matrix'), which the enum schema does not state. It also names the required parameter, though max_competitors is left entirely to 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 (compiles) plus the concrete artifacts produced: comparison matrices, pricing tiers, feature coverage, and moat evaluations. It explicitly contrasts itself with compile_research_dossier, so an agent can distinguish the two 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 three concrete triggering scenarios (market landscape analysis, pricing parity, competitive diligence) and names the alternative tool for the adjacent task (narrative research briefs). Both the when-to-use and when-not-to-use sides 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?

Adds substantial context beyond the annotations: stateless execution, 32 KB payload cap, 60 RPM rate limit, the ?demo=true escape hatch, L402 payment of 35 sats, and the HTTP 400 failure mode for invalid input. These are exactly the operational constraints (cost, throttling, failure) that annotations alone cannot convey; note the mild tension with openWorldHint=false for a tool that compiles multi-source external research.

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, then routing, then operational constraints — no filler. The final sentence is over-packed, bundling size cap, rate limit, parameter defaults, payment, and error behavior into one line, but every clause carries real 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?

An output schema exists so return values need no explanation, and annotations plus the description together cover safety, cost, limits, and failure modes. What is missing is disambiguation from the several sibling tools that perform comparable deep-research compilation.

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 three parameters, and the description adds only the research_topic name and the depth_level default ('executive_brief'). target_citations is never referenced in the description, and no extra format or sizing guidance is offered beyond what the schema 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+resource ('compiles multi-source factual research briefs') and enumerates the artifacts produced: verified citations, confidence intervals, analytical takeaways. It differentiates itself from one sibling (synthesize_neural_search) but does not distinguish itself from the near-identical conduct_deep_research_investigation or compile_mpp_research_dossier, which an agent could easily confuse it with.

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 ('synthesizing comprehensive intelligence briefings on complex technical, scientific, or market developments') and names an alternative with its selecting condition ('for rapid query search snippets, use synthesize_neural_search instead'). The gap is that it gives no exclusion against the most confusable siblings, which do nearly the same deep-research job.

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?

Goes well beyond the annotations with operational constraints: stateless edge call, 32 KB cap, 60 RPM rate limit, '?demo=true' or L402 payment (10 sats), and HTTP 400 on invalid input. The 32 KB/RPM/L402 details in particular are critical for an agent to avoid failures and are not derivable from annotations.

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

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

Front-loaded with the core purpose and the sibling routing in the first two sentences; the remaining technical limits are packed densely but each clause is a distinct, useful fact. The second sentence is a long run-on that could be split, but no sentence is wasted.

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 an output schema present, return values need not be explained, and the description still covers limits, auth, error behavior, and the key parameter default. An agent has everything needed to call this correctly and interpret success/failure.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by disclosing the 'expansion_strategy' default of 'boolean_operators', which is not in the schema. It does not elaborate on 'target_count', so it doesn't fully elevate above 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 output type — 'Generates targeted Boolean queries, semantic synonym variations, and sub-question expansions' — from an 'ambiguous prompt'. It also explicitly contrasts itself with the sibling filter_domain_intelligence, so an agent can distinguish the two without inspecting 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?

Names the triggering condition ('overcoming query vocabulary mismatches and expanding search recall across academic, code, or patent databases') and explicitly routes the alternative case ('for scoping queries to domain categories, use filter_domain_intelligence instead'). Both when-to-use 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 read-only, idempotent, non-destructive and closed-world status, yet the description still adds real operational context: statelessness, a 32 KB payload cap, 60 RPM rate limit, demo mode vs L402 payment (10 sats), and an HTTP 400 failure mode. This is meaningful disclosure beyond the structured fields.

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 purpose and formats before the operational parenthetical. Dense but nearly every clause carries information; the format list is duplicated from the title and the DOI-resolution behavior could be folded more tightly.

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

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

An output schema exists so return values need no explanation; the description instead covers the things an agent cannot infer — input size limit, rate limit, auth/payment paths, and error behavior. Nothing material for correct invocation 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%, so the baseline is 3, but the description adds value the schema does not: the default value of 'citation_style' ('bibtex_format') and the 32 KB ceiling that constrains 'source_content_or_doi'. The 'include_abstract' parameter is left entirely to the schema, keeping this below a 5.

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: 'Formats academic paper metadata and DOI identifiers into standard scholarly citation formats,' and enumerates the concrete output formats. It also names a sibling tool (summarize_temporal_timeline) to contrast against, 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 triggering contexts — generating bibliographies, validating journal references, resolving DOIs — and an explicit redirect to summarize_temporal_timeline for timeline work. The named alternative is somewhat tangential to citation formatting, but the when-to-use guidance itself 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered; the description still adds real operational context beyond them — stateless, 32 KB max, 60 RPM, L402 at 10 sats or ?demo=true, and HTTP 400 on invalid input. It stops short of describing result ordering or failure modes beyond the 400, keeping it at 4 rather than 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?

Two dense sentences, front-loaded with purpose then usage then operational constraints, with no filler. The second sentence is a long run-on packing default, payment, size and rate limits together, which costs some scannability but every clause carries 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 an output schema present, return values need no explanation, and the annotations already carry the safety hints. The description supplies the remaining decision-critical facts — default tier, cost/payment path, rate and payload limits, and the invalid-input error — so an agent can call this correctly without further probing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by disclosing the 'domain_tier' default ('academic_and_research'), which the schema does not state. It does not explain the 'time_horizon' syntax beyond the schema's own example, so it is not a 5.

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 — scoping search execution and filtering results to verified high-reputation domain registries and regulatory bodies — and identifies the concrete content classes (academic papers, SEC filings, official docs, statutes). An agent can distinguish this curated-authority search from the plain web search and fact-check 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 clause ('restricting search discovery to verified academic papers, SEC filings...') and routes the agent away with a named alternative: 'for checking specific factual claims, use verify_factual_claims instead.' The selection condition is stated, not implied.

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, yet the description adds operational context the annotations cannot convey: stateless edge call, 32 KB cap, 60 RPM limit, demo mode, L402 payment of 10 sats, and an HTTP 400 on invalid input. That is unusually rich disclosure of cost, throttling, and failure 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?

Purpose and the sibling routing come first, which is the right front-loading. The final sentence compresses six distinct facts (stateless, size, rate, default, auth, error code) into one dense clause, which is efficient but borders on cramming and could be easier to scan as discrete points.

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

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

An output schema exists, so return values need not be described. Between the purpose, the alternative routing, the payment/rate/error behavior, and full schema coverage, an agent has everything needed to decide and 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%, so the baseline is 3, but the description contributes the default for 'authority_metric' ('pagerank_and_domain_authority') that the schema does not state. It also frames 'subject_area' as an academic field, open source framework, protocol, or discipline, which slightly sharpens the schema's wording rather than merely repeating it.

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

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

States a specific verb and resource ('Identifies and ranks top domain authorities, leading researchers, and primary documentation repositories') scoped to technical topics. It also names the sibling it is not (synthesize_neural_search) for the adjacent use case, so an agent can discriminate between the two 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?

Explicit when-to-use cases ('finding primary source experts to cite or discovering foundational documentation for specialized fields') plus an explicit when-not and named alternative ('for ranking general search query snippets, use synthesize_neural_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 readOnly/idempotent/non-destructive/openWorld=false, but the description goes further: stateless edge call, 32 KB payload cap, 60 RPM rate limit, '?demo=true' or L402 payment (15 sats), and HTTP 400 on invalid input. These operational constraints are exactly the kind of context annotations cannot express.

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

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

Two sentences, with purpose front-loaded and the sibling reroute placed before the operational parenthetical. The constraints sentence is dense and run-on (size, rate limit, auth, error code all crammed into one clause), which slightly hurts scannability, but no sentence is filler.

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

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

An output schema exists so return values need not be described, annotations cover the safety profile, and the description supplies the non-obvious operational envelope (size, rate, payment, error). An agent has everything needed to call this correctly and to know when to route elsewhere.

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 each parameter is documented in-schema, so the baseline is 3. The description adds only the default value for 'timeline_resolution' and the name of the required input; it says nothing about 'ascending_order' behavior or the practical difference between the three resolution modes.

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 ('Synthesizes chronological milestone timelines') plus the input sources (search results, news archives, historical documents). It also names the sibling it is not (analyze_news_recency), so an agent can distinguish the two 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 concrete usage cases (reconstructing historical events, company histories, regulatory progression) and an explicit exclusion with the alternative for the 24-hour breaking-news case. Nothing about tool selection 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?

Beyond the annotations, it discloses statelessness, a 32 KB payload cap, a 60 RPM rate limit, authentication via demo mode or L402 payment (25 sats), and a 400 response on invalid input. These are operational constraints an agent cannot get from the schema or annotation block.

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?

Usage intent is front-loaded in the first two sentences with no filler. The second sentence becomes a dense cram of abbreviations (32 KB, 60 RPM, L402, 25 sats, HTTP 400) that reads as a run-on list rather than structured guidance.

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 an output schema, full annotation coverage, and 100% schema description coverage, the description supplies the remaining operational context (rate limits, payment, error code) needed to call it safely. It stops short of explaining how results are bundled or ranked, but the output schema likely covers that.

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. The description adds marginal value by stating search_mode's default ('hybrid_semantic_keyword'), but says nothing about max_results behavior or the semantics of the three retrieval modes beyond their names.

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

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

The description names specific verbs and resources: query expansion, relevance re-ranking, and extractive snippet bundling over multi-domain semantic search. It distinguishes itself from compile_research_dossier, but does not differentiate from overlapping siblings such as expand_search_queries, rerank_hybrid_rag_chunks, or search_gemini_grounded_web.

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 an explicit when-to-use clause (retrieving grounded web knowledge, evaluating results across domains, retrieving cited answers) and names a concrete alternative for the deep-research case. It lacks exclusions against the other search/rerank/expand siblings, which the agent must infer.

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 the description layers on genuinely new operational facts: statelessness, a 32 KB payload cap, 60 RPM throttling, demo-mode or L402 payment (20 sats), and an HTTP 400 failure mode for invalid input. A mild tension exists with openWorldHint=false given the outsourced 'authoritative consensus sources' and Lightning payment path, but this reads as a hosted proxy rather than an outright 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 with zero filler, front-loading the action and outcome before routing guidance and then operational constraints. Parenthetical packing is dense but every clause (limits, auth, error code) carries information an agent needs.

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

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

An output schema exists so return values need not be described, and the description still covers the remaining gaps an agent would hit: size limit, rate limit, statelessness, payment/auth route, and error behavior. Nothing material for correct invocation is missing at this complexity level.

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

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

Schema coverage is 100%, so baseline is 3; the description adds value by disclosing a default that the schema does not state ('verification_rigor' defaults to 'multi_source_consensus') and by tying the 32 KB cap to the claim input. It does not explain the tradeoffs between the three rigor enum values, which would have earned a 5.

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 ('Audits factual statements against authoritative consensus sources') plus the output it produces ('truthfulness scores with counter-evidence'). It explicitly distances itself from extract_scholarly_citations, but does not differentiate from the similarly named sibling audit_response_factuality, leaving one close overlap unresolved.

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 concrete triggering conditions ('checking disputed claims, detecting AI hallucinations, or validating quotes before citation') and names an alternative with the condition that selects it ('for formatting academic citations, use extract_scholarly_citations'). No guidance is offered on when to prefer it over audit_response_factuality, so it stops short of the 5 level.

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