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

No annotations are supplied, so the description carries the full burden. It usefully discloses non-obvious behavior – plain-text petition formatting applied automatically, docx_path being the PREFERRED udf input, LibreOffice-based conversion preserving bold/alignment/indent/spacing – but says nothing about overwrite semantics for out_path, error behavior, or required runtime dependencies.

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

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

One-line summary front-loads purpose, followed by a per-parameter list that earns its length for a 14-param tool. Dense but readable; no filler sentences.

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

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

For a 14-parameter, multi-mode tool with no annotations, no output schema, and no required-param declaration, the description omits two things an agent needs: which parameters are actually required for each format mode, and what the tool returns (a path? a structure?) besides the 'capabilities' hint.

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

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

Schema coverage is 0% and there are 14 parameters, so the description is doing all the work: nearly every parameter is annotated with the format it applies to and its role. A few units remain thin (draft_json as an opaque 'metadata dict', title/body/documents tagged only 'legacy export_bundle'), but compensation is strong overall.

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

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

The opening line states a specific verb+resource ('Unified document export') and enumerates the five formats plus a capabilities mode, so the agent can distinguish it immediately from the search/get siblings.

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

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

It routes the caller per format by tying each parameter to the format it serves (draft_path for docx/plain, out_dir for bundle, etc.) and explicitly notes udf_path 'replaces convert_udf_to_docx/pdf'. It stops short of stating when NOT to use this tool or which parameter combinations are mandatory per format.

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?

With no annotations, the description carries the full burden and does well: it discloses output deduplication (full_text, raw, metadata.content omitted by default), the 40,000-char pagination threshold, paragraph-boundary splitting, and the pagination fields returned. It does not state that the operation is read-only, nor any auth/rate-limit or missing-document error behavior, which keeps it from a 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?

Front-loaded one-line summary followed by clearly labeled Args and Returns blocks; every sentence adds usable information at 0% schema coverage. The Returns section restates the deduplication rule already implied by include_raw, which is minor redundancy but not enough to hurt.

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

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

There is no output schema, so describing the return shape (markdown field, current_page/total_pages/total_chars) is necessary and present; the pagination contract is fully explained. Missing pieces are error/not-found behavior and an explicit read-only guarantee, which an agent would reasonably want for a fetch tool.

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

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

Schema description coverage is 0%, so the description must document all four parameters, and it does: source as identifier, document_id 'must not be empty', include_raw with default and debugging rationale, and page_number as 1-indexed with default 1 plus the threshold that activates it. This fully compensates for the bare 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 with explicit scope: 'Fetch a single document by ID from the given source.' That distinguishes it by implication from the search tools (search_decisions, search_legislation) and from get_legislation, since retrieval is keyed by ID. It never names an alternative explicitly, so it falls short of a 5.

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?

Usage is only implied: 'by ID from the given source' suggests this is the fetch stage after a search, and 'include_raw ... (debugging)' hints at a debug use case. There is no statement of when to prefer this over get_legislation or search_local_corpus, and no preconditions (e.g., the ID must come from a prior search).

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?

With no annotations provided, the description carries the full behavioral burden. It does disclose useful behavior: the pagination model (40,000 chars/page) and the return shape including current_page/total_pages/total_chars. It omits auth requirements, error behavior, and an explicit read-only statement (only implied by 'Get'), leaving meaningful gaps for a no-annotation tool.

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 docstring-style layout is front-loaded with the purpose, then Args, then Returns, with no filler sentences. It is appropriately sized for a four-parameter tool, though the Returns section is terse and could be marginally clearer.

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

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

There is no output schema, but the description compensates by describing the returned Dict per part and the pagination fields. Combined with full parameter coverage, an agent has enough to invoke it correctly; only auth/error context 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 0%, so the description must compensate, and it largely does: it documents all four parameters, including document_id, source, the three valid 'part' values, and page_number with its page size. A minor inconsistency exists where the description says source defaults to 'mevzuat' while the schema default is null.

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 ('Get legislation content from the Mevzuat source') and enumerates the retrieval modes ('document', 'article_tree', 'gerekce'), so the agent knows exactly what it returns. It does not, however, differentiate itself from siblings like search_legislation, get_document, or mevzuat_madde_getir, so it falls short of a 5.

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?

Usage is implied through the 'part' modes: the agent can infer to use 'document' for full text, 'article_tree' for structure, and 'gerekce' for rationale. There is no explicit guidance on when to choose this tool over the sibling search/get tools, nor any stated prerequisites, so it remains implied rather than explicit.

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

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

With no annotations, the description carries the full behavioral burden and does well: it enumerates what is checked (source smoke, breakers, indexes, cron jobs), explains that scheduled_jobs is read from log files, and defines the "degraded" condition (late job or rc != 0). It omits any statement of read-only safety, permissions, or latency, which keeps it short of a 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?

Purpose is front-loaded in the first sentence, with return-value detail following in a logical order. It is appropriately sized for a no-arg diagnostic, though the enumerated job list is slightly dense.

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

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

There is no output schema, so the description must document return values, and it does: overall status, source smoke summary, breaker states, index status, and scheduled_jobs semantics including the degraded rule. With no parameters and a read-only-seeming operation, the remaining gap (safety/permissions profile) is small.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The description correctly implies no input is required.

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

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

Opens with a specific verb and resource scope: "Run a consolidated health check across sources, breakers, indexes and cron jobs." This clearly distinguishes it from every sibling (all search/get/retrieval tools), so an agent can identify it as the operational diagnostic 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?

Usage is implied by the diagnostic framing, but there is no explicit when-to-use guidance, no statement of when-not to use it, and no alternatives named (none of the siblings are close substitutes, so this is a minor gap). A caller can infer it is a monitoring entry point but is given no trigger conditions.

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?

With no annotations, the description carries the full burden and largely does so: it discloses the no-restart behavior, the return fields (ok, loaded, already_loaded, invalid_categories), and the non-obvious caveat that the MCP client may need to refresh its tool list. It stops short of saying whether repeated loads are idempotent or what the cost/limits of loading are.

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 the no-restart constraint, then a scannable category list. The embedded sub-tool descriptions add length, but they earn their place by previewing what each category unlocks; only minor tidying is warranted.

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, so the description correctly supplies a Returns section, and it lists the full category vocabulary. For a meta-tool with one parameter this is close to sufficient; only failure/edge behavior (e.g., what invalid categories do) is left implicit.

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

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

Schema description coverage is 0% and the schema provides no enum, so the description is the only source of valid values, and it enumerates all category names with examples like ["drafting", "files"]. The sub-tool glosses are useful but occasionally muddy, mixing Turkish labels, which slightly weakens the mapping of names to categories.

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 ('Load extra tool categories into the running MCP server') plus the key constraint 'no restart'. This clearly distinguishes it from all sibling legal-research tools, which retrieve content rather than mutate the server's tool surface.

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 context: 'Core profile registers 11 tools. Everything else waits here; load a category when the task needs it.' This tells the agent exactly when to reach for it. It lacks an explicit when-not clause (e.g., what to do if a category is already loaded), which keeps it short of a 5.

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

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

With no annotations, the description carries the full burden and does well: it declares the offline/local nature, that the corpus only contains already-fetched documents, the different recall behavior of each mode, and the fields returned. It omits pagination/limit behavior and any auth context, keeping it from a 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?

Front-loaded with the core purpose, then modes, then the critical false-negative caveat, then result shape. Dense but every clause carries information; the inline key:value layout reads slightly like notes rather than prose but wastes nothing.

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 4-parameter search tool with no output schema, the description supplies the mode semantics, the scope-limiter, the return fields, and the important operational caveat about empty results. What remains missing (limit/pagination, ranking details) is minor.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for the two non-obvious parameters: mode is given three named values with semantic explanations, and mevzuat_no is explained with a concrete example ('6098'). Only 'limit' is left implicit, which is a minor gap given the obvious default of 20.

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 ('YEREL korpusta MADDE bazında arama') and scopes it to offline, article-level search, which cleanly separates it from the remote sibling search_legislation. An agent can pick 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?

Explicitly warns that 0 results does not mean 'no provision' and routes the agent to search_legislation, and it explains when to pick each mode (lexical vs semantic vs hybrid). It lacks an explicit statement of the positive condition for using this local tool over the remote one, so it falls just short of 5.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the offline nature and the NOT_FOUND failure mode with an anti-hallucination warning, but says nothing about permissions, response shape, or whether the corpus can be stale.

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

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

Three short sentences, front-loaded with the core action and scope, then format examples, then failure handling. 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 two-parameter lookup with no output schema or annotations, the description covers what is returned (full article text), the offline source, accepted input formats, and the failure mode. The only real gap is the meaning/format of mevzuat_no.

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

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

Schema description coverage is 0%, so the description must compensate. It does give concrete accepted formats for madde_no ("390", "12/A", "Geçici 1"), which is genuinely useful, but leaves mevzuat_no completely unexplained.

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: retrieving the FULL text of a single article from the local (offline) corpus. It implicitly distinguishes itself from get_legislation by framing this as the offline source, so an agent can tell them apart.

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

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

Explicitly routes the agent to the live alternative: if the article is not in the corpus, it returns NOT_FOUND and the agent should call get_legislation instead of fabricating. This is clear fallback guidance, though it does not spell out upfront when to prefer this tool over the live one in the normal case.

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

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

No annotations are provided, so the description carries the full burden. It usefully enumerates the return payload (citation_safe_count, warnings, recommended_next_steps), signaling quality/citation concerns, but omits side effects like where generated_files are written, whether output_dir is required for file generation, and any rate limits or permissions.

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 action and followed by the return contract. Efficiently sized, though the field enumeration is dense prose that would read better as a list.

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 5-parameter composite tool with no output schema and no annotations, the description leaves the parameter contract and side effects largely unexplained. Enumerating return fields helps but does not cover how to call it correctly.

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

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

Schema description coverage is 0% and none of the 5 parameters (filters, sources, output_dir, fetch_count) are explained in the description. 'query' appears only implicitly inside the return-field list. With low coverage the description should compensate but does not.

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 compound purpose: 'Search sources, fetch documents, and build a research bundle.' The verb+resource is clear, but the compound nature makes it hard to distinguish from siblings like search_local_corpus or search_decisions when only the search portion is needed; no sibling is named.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives among the 10 sibling search/get tools. The agent must infer whether this is the right entry point versus narrower search tools.

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

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

With no annotations, the description carries the full burden and does so thoroughly: two-pass AND→OR fallback reported via warnings/fallback_to_or, character whitelist and query sanitization, INVALID_COURT_TYPE rejection to avoid indistinguishable silent zero-results, unstemmed-index token behavior, and the AİHM TUR→ENG/FRE language fallback. This is unusually rich operational 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?

The purpose and rules are front-loaded and organized under headers, which helps with 14 parameters. However the prose is bloated with dramatized emphasis ('HARD RULES — no exceptions', repeated ⚠️ blocks, emoji) that adds length without adding actionable detail, making it heavier than necessary for the information conveyed.

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 14-parameter, zero-annotation research tool, the description is complete: query construction, source switching, filtering, pagination, and fallback semantics are all covered, and an output schema exists to carry the return structure. Nothing essential to 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 coverage is 0%, so the description must compensate and largely does: it enumerates valid source values with their distinct behaviors, exact court_types spellings, birimAdi chamber codes, date format and inclusivity, esas_no/karar_no YIL/SIRA format, sort_by inference rules, and the effects of include_snippets/include_raw/dil. Nearly all 14 parameters gain meaning beyond their bare typed 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?

Opens with a specific verb+resource+scope: it retrieves live court decisions, precedents, case law and legislation from official sources. It explicitly differentiates itself from siblings, stating it is the only tool that fetches live from Bedesten/Yargıtay/Mevzuat, and names search_local_corpus as the tool that cannot discover decisions. An agent can identify its role without reading 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 ('For ANY case-law question ... you MUST call THIS tool first'), when-not-to-use ('Do NOT answer from memory', 'Do NOT use search_local_corpus to FIND decisions'), and the follow-up workflow (verify via get_document). Alternatives and preconditions are spelled out rather than inferred.

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?

With no annotations, the description carries the full burden and does disclose non-obvious behavior: abbreviations in query are auto-routed to mevzuat_no, scope='article' requires document_id, and the return shape (ok, query, results, total_results, warnings). It stops short of stating pagination behavior, error handling, or any auth/cost constraints, keeping it below a 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?

Front-loaded with the highest-value routing rules before the parameter list, and the Args/Returns structure is scannable. Some entries are terse to the point of near-redundancy (limit: 'Max results'), but overall every section earns its place.

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

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

For a 10-parameter tool with no annotations and no output schema, the description covers parameter meaning and summarizes the return dict, which is the right level of detail. Gaps remain around limit/pagination interplay and failure modes, but nothing critical to invoking 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 0%, yet the description documents all ten parameters with examples and constraints: mevzuat_adi with a worked example, mevzuat_no with '6698'→KVKK, scope values 'law'/'article' plus the document_id dependency, sort_by's three options, and mevzuat_tur_list's type values. This fully compensates for the empty 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+resource ('Search legislation via the Mevzuat source') and immediately clarifies the three search modes (title, number, body-text). It does not explicitly differentiate itself from siblings like search_decisions, mevzuat_korpus_ara, or search_local_corpus, so an agent must infer the boundary, but the core purpose is unambiguous.

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

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

Gives concrete routing guidance: use mevzuat_adi for titles, mevzuat_no for official numbers with an explicit warning ('never guess the number; if unsure use mevzuat_adi first'), and query for body-text. This is strong intra-tool guidance, but it never says when to prefer this tool over sibling search tools, so no explicit alternatives are named.

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

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

No annotations are provided, so the description carries the full burden, and it delivers: corpus staleness, the mandated verification workflow, per-mode latency ('rrf' SLOW — minutes on a large corpus), AND-match semantics, and diacritic folding. It also discloses the return shape via 'related_quotes — matched passages', which is valuable with 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 one-line purpose, then cleanly sectioned into Roles, QUERY FORM, and Args. The length is justified by the 16 undocumented parameters and the query-syntax rules; 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?

Given 16 params, 0% schema coverage, no annotations, and no output schema, the description still tells an agent how to phrase the query, which mode to pick and its cost, how to filter, and what the results contain. Nothing essential to a correct call 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?

With 0% schema description coverage the description must compensate, and it does for the high-impact params: query form and quoting, every mode value with performance trade-offs, limit, sort ('lexical mode only'), provider, and the group of flat filters explained as equivalents to 'filters'. Minor gaps remain (accepted values for content_status, date format, the bundled content filters), which keeps it 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?

Opens with 'Concept DISCOVERY over the local corpus' and specifies the resource (decisions fetched this session or via corpus crawl) and the trigger condition (when exact wording is unknown). It explicitly differentiates itself from the sibling search_decisions, so an agent can choose between them without reading 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?

States the complementary roles directly: 'THIS tool = DISCOVERY over the local corpus; search_decisions = live CURRENT search + citation verification.' It gives an explicit caveat ('the corpus may lag') and a required follow-up ('always confirm any decision you cite with search_decisions + get_document first'), which is precisely the when/when-not/alternative guidance.

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