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

Annotations already cover read-only, idempotent and non-destructive, yet the description adds real behavior: 100-tag cap, 50-page cap, most-used-first ordering, min_count being ignored in tag mode, and plain-text output format. The only thing missing is how the min_count threshold interacts with the 100-tag cap when many tags qualify.

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 resource and its terminological caveat, then mode-by-mode behavior, then sibling routing. Dense but every clause carries information; nothing is redundant.

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-optional-parameter read tool with no output schema, the description supplies result format ('path - title'), size caps, ordering, and sibling alternatives. An agent can call it correctly and predict the response without further information.

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 goes further by documenting the cross-parameter interaction (min_count is ignored when tag is supplied) and the ordering of the untagged listing. That is genuine meaning beyond the schema, though tag format/normalization (case, matching rules) is unstated.

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 ('Browse the wiki by tag') and immediately disambiguates terminology ('tags' frontmatter field; 'category' here means tag). It then defines the two distinct modes of operation, so an agent knows exactly what the tool returns in each case.

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 routing guidance: use wiki_entity_search for named things and wiki_query for free-text questions, implicitly reserving this tool for tag-based exploration. The two modes (no tag vs. tag) are each tied to their own output shape.

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

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

Beyond the annotations (which already declare readOnly, idempotent, non-destructive, closed-world), the description discloses the return format ('plain text: the match count, then up to 50 lines of score path - title'), the ordering ('lowest score first'), and the silent 50-line cap plus omission of unscored pages. Those are exactly the behavioral traits the agent needs and cannot get from 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?

One tightly packed passage: purpose and filter first, return shape second, safety flag third, usage routing last. Every clause (range, exclusion, truncation, ordering, alternative tool) carries information; nothing is redundant 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?

There is no output schema, but the description fully compensates by describing the exact return structure, ordering, and truncation limit. Combined with zero required parameters and complete annotation coverage, an agent has everything needed to invoke and interpret this tool correctly.

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

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

Schema coverage is 100% and both parameters already document their inclusive bounds and defaults, so the schema does the heavy lifting. The description only restates the range semantics ('between min_confidence and max_confidence') without adding format, edge-case, or interaction details beyond the schema, making 3 the correct baseline.

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

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

The description opens with a specific verb and resource ('List wiki pages') plus the exact filtering dimension (frontmatter confidence 0.0-1.0 between min_confidence and max_confidence). It also states the exclusion rule for pages without a confidence value, so an agent knows precisely what the result set is and how it differs from siblings like wiki_dashboard or wiki_query.

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 concrete call pattern ('use max_confidence=0.5 to find weak pages to recheck') and names the alternative tool for a different need ('use wiki_dashboard for the overall distribution'). When-to-use and when-to-use-something-else are both covered without 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, non-destructive, and closed-world, so safety is covered; the description adds the return format (plain-text Markdown) and the concrete confidence thresholds (>=0.8 high, <0.5 low) that the agent could not infer elsewhere. It stops short of noting whether results are cached or how large a wiki is practically handled, but for a zero-parameter aggregate read the disclosure is strong.

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

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

Three sentences, front-loaded with the payload contents, then the return format and safety profile, then the routing advice. Every clause carries distinct information and none repeats the title verbatim.

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 compensates by enumerating the metrics returned and the Markdown format. For a parameterless read-only aggregate, nothing an agent needs to select or 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?

The tool takes no parameters, so per the baseline this starts at 4. The description correctly reinforces "no parameters," preventing an agent from inventing filtering arguments, though there is nothing further to document.

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 ("Overview of the whole wiki in one call") and enumerates exactly what the overview contains: total page count, pages per type, per lifecycle state, and confidence buckets. This is clearly distinguishable from siblings like wiki_confidence and wiki_lifecycle, which it names as the drill-down 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?

States both when to call it ("Call it first to see the wiki's size and health") and which alternatives to use for follow-up detail (wiki_lifecycle, wiki_confidence for page lists). Ordering guidance is explicit 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?

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description goes further and discloses the output shape ('plain text: the count, then up to 50 lines of [type] path - title, sorted by title') including a hard 50-line cap and sort order that appear nowhere in structured fields. That cap is exactly the kind of behavioral trait an agent needs in order to decide whether to narrow the query.

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

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

A single dense paragraph that is front-loaded with the resource definition, then matching rules, then return format, then routing. Parenthetical enumerations and separators keep it scannable and no sentence is redundant.

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 carries the burden of describing return values, and it does so fully: count line, per-line format, cap, and sort order. Combined with zero required parameters and full schema coverage, an agent has everything needed to call and interpret this tool.

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

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

Schema coverage is 100%, so the schema baseline would be 3, but the description adds meaning the schema does not: it clarifies that name matches against the title OR path (the schema only says 'Entity name substring'), and it spells out the boolean combination and the list-everything default. Those are non-obvious semantics beyond the per-parameter descriptions.

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

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

The description names a specific verb and resource ('Find entity pages') and enumerates the entity family (people, orgs, tools, libraries, APIs, projects, concepts). It also defines the underlying selection precisely as 'wiki pages with type: entity', which distinguishes it from the generic wiki_search sibling without needing its 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?

The final sentence explicitly routes the agent elsewhere: 'Use wiki_query for free-text questions and wiki_category_browse for tags', naming both alternatives and the condition that selects each. The matching rules ('when both are given both must match; with neither, every entity is listed') further tell the agent how to compose a call.

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 readOnly, idempotent, non-destructive, so the description is not obligated to restate safety; it does add real behavior beyond them: output is truncated at 200 KB, the call fails when the file is missing, and the build prerequisite must be satisfied. The only gap is what an agent should do after hitting the 200 KB cutoff, which is not addressed.

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 front-loaded paragraph: purpose, format menu, truncation limit, failure mode, prerequisite, then the sibling routing. Every sentence carries information, with only the redundant 'Read-only.' clause duplicating 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 one-parameter tool with no output schema, the description must explain the return shape and it does: text output, 200 KB cap, and the special 'list' variant returning JSON with sizes. Combined with the failure and prerequisite notes, an agent has everything needed 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 3 would be the baseline, but the description goes further by defining what each enum value actually yields (short index vs. flattened pages vs. schema.org graph vs. JSON file list with sizes). That meaning is absent from the schema, which only says 'Which export format to return.'

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 concrete verb and resource (return one generated export file from site/) and enumerates every accepted format with a short gloss of each, so the agent knows exactly what the tool produces. It also distinguishes itself from wiki_query by noting that tool is cheaper for specific facts.

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 frames the use case (load the whole wiki at once) and names the alternative with the condition that selects it (wiki_query for specific facts). It also supplies the prerequisite that the build must have been run first, which an agent cannot 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description still adds real behavior beyond that: it discloses the return shape (plain text, match count first), a hard cap of 50 lines, the 'last_updated path - title' line format, and newest-first ordering. Only the on-disk pagination escape hatch (how to see beyond 50) is left unstated.

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 short sentences with zero filler: purpose, return format, safety, then routing to siblings. Each sentence carries distinct information, and the core purpose is front-loaded before the operational details.

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

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

There is no output schema, and the description compensates by describing the return text, its fields, ordering, and truncation limit. Combined with annotations covering read-only behavior and a single fully-documented enum parameter, nothing an agent needs to call this 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 coverage is 100% and the enum already lists all five states, so the baseline is 3. The description goes further by tying states to intent – 'stale' or 'draft' are the ones that surface pages needing updates – which is meaning not present in the schema's 'Which lifecycle state to filter by.'

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 ('List wiki pages whose frontmatter lifecycle equals state') plus the exact filter dimension, which distinguishes it from wiki_search (content search), wiki_query, and wiki_category_browse. An agent can tell immediately what universe of results to expect.

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 guidance ('use stale or draft to find pages to update') and names a concrete alternative with its distinct purpose ('use wiki_dashboard to see how many pages are in each state'). The when-to-use boundary is fully resolvable without opening another schema.

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

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

Annotations already declare readOnly, idempotent and non-destructive, and the description reinforces that with "reports and changes nothing." It adds genuinely non-obvious behavior beyond the annotations: the exact result keys and, critically, that orphans and broken_links are capped at 50 each, which tells an agent the output may be truncated rather than 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 operation and findings, then the return shape, then the safety note, then routing to alternatives. Every sentence carries distinct information with no restatement of the title or name.

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 enumerates the return JSON fields and the 50-item cap, so an agent knows what it will get back. Combined with read-only annotations, nothing needed to call this 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline applies. It does implicitly confirm the scope is the whole wiki/ tree with no filtering options, which is the only parameter-adjacent fact an agent would need.

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?

Names a specific verb and resource ("Check the link structure of wiki/") and then defines both findings precisely: orphan pages as those with no inbound [[wikilinks]] (with index/overview/log explicitly exempt) and broken [[wikilinks]] pointing to no page. This is far more specific than the title and lets an agent distinguish it from sibling review tools like wiki_confidence or wiki_lifecycle.

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 timing triggers ("after wiki_sync or before publishing") and names the alternative tools for a different job ("wiki_lifecycle or wiki_confidence to review page quality"). Both when-to-use and when-to-use-something-else 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description reinforces "Read-only." Beyond that it adds genuinely new behavioral context: the exact directory, one-file-per-session granularity, deterministic oldest-first ordering, and the fact that project/date are derived from each file's frontmatter, which signals metadata can be missing or inconsistent.

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 action and scope, then the return shape, then the usage workflow. Every sentence carries distinct information: location, output fields, provenance, safety, and next step. No repetition of the title 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?

There is no output schema, and the description compensates by enumerating the returned object fields (path, project, date, filename, size_bytes) and explaining where project and date originate. For a single-optional-parameter listing tool, nothing an agent needs to call it correctly or interpret results 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 single optional `project` parameter is documented in the schema as a substring match with the meaning of omitting it. The description adds no parameter-level detail beyond that, so the schema is doing the work and 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?

The description names a specific verb and resource ("List raw session transcripts") and pins down scope ("in raw/sessions/"), granularity (one markdown file per agent session), and ordering ("sorted by path, oldest first"). An agent can distinguish this listing tool from content-oriented siblings like wiki_search and wiki_query 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?

It gives an explicit usage path: "Use it to see which sessions exist for a project, then open one with wiki_read_page," naming the follow-up sibling directly. It lacks an explicit when-not statement (e.g. use wiki_search instead to find sessions by content), 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: keyword ranking with rare-word weighting, no LLM or embeddings, service pages skipped, project overviews ranked below sessions, 'via <name>' expansion for tool/topic co-occurrence, and raw-transcript fallback. The only small gap is that it doesn't say what happens when both wiki and raw produce nothing beyond the index.md fallback.

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 and dense with no filler sentences, but the middle sentences are long and clause-stacked (ranking rules, via-marking, fallback), which makes the ranking paragraph harder to scan quickly. Slight tightening into bullets would improve it.

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, and the description compensates fully by describing the return shape (up to max_pages paths, ~400-char snippets, overview.md or index.md appendix). For a three-parameter read-only search tool whose annotations are already complete, nothing an agent needs 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 100% so the baseline is 3, but the description adds real meaning: include_raw's tri-state behavior is restated as a fallback policy tied to matching, max_pages is tied to the ~400-character snippet output, and the question parameter's language-independence and use of stored original requests are explained.

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 concrete verb-plus-resource framing ('Start here for questions about the user's past work') and gives example queries that pin down the intent. It explicitly contrasts itself with wiki_read_page (open a full page) and wiki_search (exact wording), so an agent can distinguish it from siblings 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?

Says exactly when to use it (natural-language questions about past work, any language), when to use alternatives (wiki_search for exact wording, wiki_read_page for full content), and states the no-match fallback path. Both the selection condition and the exclusions are explicit.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered elsewhere. The description still adds real behavior beyond that: no truncation, the path allowlist, and the three error conditions (outside the set, path escape, nonexistent). That is useful but it is largely a restatement of the access contract rather than deeper operational context such as size limits or encoding.

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 return guarantee, then the path constraint, then errors, then sibling routing — a sensible order with no filler. The standalone "Read-only." sentence is mildly redundant against readOnlyHint but cheap enough to keep.

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 one parameter, no output schema and full annotation coverage, the description covers what an agent must know: what comes back, what paths are legal, and what happens on failure. Only minor gaps remain, such as behavior on very large files or binary content.

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 the sole path parameter with an example. The description adds the allowed-directory constraint and the requirement that the path be relative to the sessionwiki folder, which is genuinely beyond the schema, but it does not add format or edge-case detail beyond that single constraint.

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 ("Return the full text of one file") plus two distinguishing properties: unmodified and not truncated. That clearly separates it from the snippet-returning siblings wiki_query and wiki_search without opening their 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?

Explicitly routes path discovery to wiki_query, wiki_search or wiki_list_sources, making the division of labor between discovery tools and this single-file reader unambiguous. An agent knows to search first and read second.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds operationally important behavior: 200-match truncation, skipping files over 4 MiB, a 256 MiB per-call read cap, and a scan_incomplete signal for incomplete scans. Those limits directly affect result interpretation and are not available from the annotations or 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 matching rule, then return shape, then limits, then alternatives — a sound ordering with no filler. The middle section is a semicolon-dense run-on that could be split into bullets, which costs it the top score.

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 supplies the full return contract ({term, matches, truncated, scan_incomplete, files_scanned, files_total, skipped_oversize_files}) and explains which fields indicate partial results. Nothing essential for correct invocation or result interpretation 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 100%, so baseline is 3; the description nonetheless adds meaning beyond the schema by specifying case-insensitivity and line-by-line matching semantics for term, and by tying include_raw to the raw/sessions/ path. It stops short of elaborating further edge cases for term syntax, so 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 plus the exact matching mechanism: 'case-insensitive substring match, line by line, over wiki/ pages'. It also scopes the raw/ extension to include_raw=true, so an agent can distinguish it from ranked-search siblings immediately.

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: 'Use wiki_query instead for ranked, question-style lookup' and 'open a hit with wiki_read_page'. This is a clear when-to-use plus named alternatives, the strongest form of 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?

The annotations already declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the write and safety profile is partly covered. The description still adds real value beyond them: default dry-run behavior, the confirm gate, the no-overwrite guarantee that makes repetition safe, a possible site/ rebuild side effect, a 256 KB output cap and a 120 s timeout. The only shortfall is that the return payload is described in size, not in structure.

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, each doing distinct work: what it converts, the safe default, the confirm requirement with the user-ask, and the operational envelope (idempotency, site rebuild, output size, timeout). It is front-loaded with purpose and scope. It is dense and slightly run-on, 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?

There is no output schema, so the description correctly compensates by describing the return (converter output, last 256 KB) and a failure condition (120 s). Safety, idempotency, side effects, and prerequisites are all covered for a mutating import tool. The only gap is that the shape of the returned converter output is unspecified beyond its size.

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 each parameter already documents its own interaction ('Without confirm=true the call always runs as a dry-run regardless of dry_run'), so the schema does the heavy lifting. The description's 'writes only with dry_run=false and confirm=true' restates the same rule rather than adding syntax or format detail. This is the baseline case where the schema, not the prose, carries 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?

The description gives a specific verb and resource — convert local agent session stores (Claude Code, Codex, Cursor, ZCode, OpenCode) into markdown under raw/sessions/ — and names the boundary against a sibling by pointing at wiki_list_sources for the coverage question. An agent can distinguish this from list/query/search 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?

It states the triggering condition explicitly ('Use it when wiki_list_sources lacks recent sessions'), the safe default (dry run), the exact gate for writing (dry_run=false plus confirm=true), and a human-in-the-loop prerequisite ('ask the user before that'). Nothing about when to call versus when not to call 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.