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

No annotations are provided, so the description carries full burden. It discloses wiki index rebuild deduplication and independence of operations, but does not mention safety aspects (e.g., possibility of destructive writes) or response format. Lacks warnings about auth or rate limits.

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

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

The description is front-loaded with purpose, includes examples and constraints in a clear, concise manner. Every sentence adds useful information without redundancy.

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

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

Given the tool's complexity (batch execution) and no output schema, the description covers key behaviors: operation independence, no nesting, deduplication. However, it does not describe the response structure, ordering beyond schema's 'sequentially', or potential limits on operation count.

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% (operations array described), so baseline is 3. The description adds value by providing concrete examples of tool combinations and explicitly forbidding nested batch calls, which is not in the schema.

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

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

The description explicitly states 'Execute multiple tool calls in a single request,' providing a specific verb and resource. It distinguishes the batch tool from sibling tools by explaining its batching capability and use case for reducing per-request bills.

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

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

The description clearly indicates when to use the tool: 'Reduces tool-call count for LLM subscriptions that bill per-request (e.g. GitHub Copilot).' It also specifies supported operations (any combination), exclusion of nested batch calls, and behavior of independent operations with per-failure non-abort.

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 discloses key behaviors: it persists artifacts under a specific path, optionally traces variable references, and currently supports only COBOL. It does not mention permissions, reversibility, or side effects of overwriting artifacts.

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, no redundancy, front-loaded with the main action. Every sentence adds value: what it does, supported languages, output location, optional parameter.

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

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

Given no output schema, the description explains the transformation (AST, model, summary) and artifact persistence. It covers language support and optional tracing, though it does not mention if the tool returns anything or only persists files.

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 no new semantics beyond the schema; it restates 'path' and 'trace_variable' without elaboration on format or constraints.

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

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

The description clearly states it parses a source file into structured code knowledge (AST, normalized model, summary), specifies supported COBOL extensions, and distinguishes from sibling tools like raw_read (read raw) or code_query (query code).

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 implies usage for code analysis but does not explicitly state when to use this tool versus alternatives like raw_read or code_query. No when-not or exclusion guidance is provided.

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?

For each query type, the description explains what is returned (e.g., reads/writes, affected programs, flow, lineage, edges) and mentions uncertainty markers and transitive chains, providing full behavioral clarity without annotations.

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

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

The description is well-organized in a bullet list, front-loaded with purpose, and every sentence is informative without redundancy.

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

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

Given 17 parameters and no output schema, the description compensates by detailing return behaviors per query type, making it sufficiently complete for an agent.

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 grouping parameters per query type and explaining their role, which aids selection.

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

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

The description clearly states the tool queries parsed code knowledge, lists five distinct query types with specific purposes, and differentiates from sibling tools like code_parse and knowledge_ingest.

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

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

The description provides detailed guidance on when to use each query type and which parameters apply, but lacks explicit exclusions or alternatives for sibling tools.

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

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

Without annotations, the description discloses several behavioral traits: files already in raw/ are skipped, index is rebuilt once after digest_write, auto-classification and auto-routing occur, and timestamps are added. It also details the extraction process (per-page PDF, per-sheet XLSX, etc.). However, it doesn't mention side effects like overwriting existing data or security/auth requirements.

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

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

The description is well-structured with clear sections for each mode and bullet points for parameters. It is concise, with no extraneous information, and every sentence adds value. However, it could be slightly more condensed without losing clarity.

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 complexity (9 parameters, two modes, no output schema, no annotations), the description is fairly complete. It explains the overall pipeline, each mode's workflow, and key behaviors like file skipping and index rebuilding. It lacks an explanation of the return value or output format, but the absence of an output schema lessens the need.

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

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

The input schema already provides 100% description coverage for all 9 parameters. The tool description adds value by explaining the purpose of the mode parameter and summarizing the role of batch parameters (e.g., 'Scans a directory... imports to raw/'). This contextualizes the parameters beyond their schema definitions.

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

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

The description clearly states it is a knowledge ingestion pipeline with two distinct modes: batch (import, extract, chunk, pack) and digest_write (write LLM summaries to wiki). It differentiates from sibling tools like raw_ingest (which only imports raw files) and wiki_write (which only writes pages) by covering the full ingestion and summary writing process.

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

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

The description explains when to use each mode: batch for importing and packing source documents, digest_write for writing wiki summaries. However, it does not explicitly state when not to use the tool or mention alternative tools like raw_ingest for simpler raw file imports. The context is clear but lacks explicit exclusion criteria.

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. It describes matching behavior (frontmatter sources and inline raw references), exclusions (parsed artifacts), and output (sorted by recency/size plus coverage ratio). No contradictions.

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

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

The description is two sentences, front-loaded with the core purpose in the first sentence, and no wasted words.

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

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

The description covers purpose, matching method, exclusions, and output. Although no output schema is provided, it mentions returned items and coverage ratio. For a reporting tool, this is sufficient.

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

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

Schema coverage is 100% with descriptions for all three parameters. The description adds context about sort options (recency/size) aligning with the enum, and implies limit defaults. However, it doesn't add much beyond what the schema already provides, so baseline 3.

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

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

The description clearly states the tool reports which raw files are not referenced by any wiki page, answering 'what should I compile next?'. It specifies matching frontmatter 'sources' and inline 'raw/...' references, and that parsed artifacts are excluded. This distinctively sets it apart from siblings like raw_list and raw_ingest.

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

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

The description explicitly answers 'what should I compile next?', indicating when to use. It clarifies that parsed artifacts are excluded. However, it does not mention when not to use or provide alternative tools, but the context is clear.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively covers key behaviors: image return and required follow-up action, arXiv URL conversion, directory import behavior, token format acceptance, and fallback to REST API v2 for older Jira Server. While it could mention rate limits or error handling, the level of detail is commendable for a complex 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 description is structured with a leading sentence followed by a bulleted list for each mode, making it scannable. It front-loads the core purpose. However, it is lengthy (multiple paragraphs), which is justified by the tool's complexity. Every sentence contributes meaningful content, ensuring no redundancy.

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

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

Given the tool's high complexity (4 modes, 17 parameters, no output schema), the description provides thorough context: token handling for each service, image behavior, directory import patterns, and more. It lacks details about return values or error states, but the description is rich enough for an AI agent to use the tool effectively.

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

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

Although the input schema already describes all 17 parameters (100% coverage), the description adds significant value by grouping parameters by mode, explaining token formats, and clarifying behaviors like arXiv URL auto-conversion and auto_version semantics. This contextual information goes beyond mere parameter listing, aiding correct parameter selection.

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

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

The description clearly states the tool's purpose: 'Ingest raw source documents into the knowledge base.' It enumerates four distinct modes with specific verbs ('add', 'fetch', 'import_confluence', 'import_jira'), making it easy for an AI agent to understand the scope. The purpose is well-differentiated from sibling tools like `raw_list`, `raw_read`, and `knowledge_ingest`, which handle different aspects of raw or knowledge management.

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

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

The description provides explicit guidance on when to use each mode, including detailed conditions for image handling ('you MUST immediately call wiki_write'), token format for Confluence/Jira, and auto-versioning. However, it does not explicitly state when NOT to use this tool (e.g., when `knowledge_ingest` would be more appropriate). This minor omission prevents a higher score.

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

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

The description implies a read-only list operation but does not explicitly state behavioral traits such as idempotency, rate limits, or authentication requirements. Without annotations, the description provides minimal transparency beyond the core action.

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 a single, well-structured sentence that front-loads the purpose. No unnecessary words or redundancy.

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

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

For a tool with no parameters and no output schema, the description adequately conveys what the tool does. However, it omits potential details like pagination, sorting, or result limits, which could be useful for an agent.

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

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

There are no parameters, so the schema coverage is 100%. The description adds no parameter information, which is acceptable given zero parameters. Baseline score of 4 is appropriate.

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

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

The description clearly states the tool lists all raw source documents and specifies the metadata fields returned. The verb 'list' and resource 'raw source documents' is specific and unambiguous, and no sibling tool overlaps directly.

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 guidance is provided on when to use this tool versus alternatives like raw_coverage or raw_versions. The description lacks any context about suitable use cases or scenarios.

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 fully discloses behavior: raw files are immutable and read-only. It explains return formats per file type (content string for text/SVG, extracted text for documents, metadata only for binary) and pagination nuances (e.g., XLSX always returns sheet_names). This is highly transparent.

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

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

The description is well-structured: a concise opening sentence, followed by a clear section on pagination by format, and a final recommendation. Every sentence adds value, and there is no redundancy.

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

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

Given no output schema, the description adequately explains what is returned for each file type and how pagination works. It covers all common formats. Missing details on error handling (e.g., missing file) or metadata structure for binary files, but overall it is sufficiently complete for a read 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%, but the description adds significant value by linking parameters to specific formats (e.g., 'pages' for PDF/PPTX, 'sheet' for XLSX) and explaining defaults (limit=200) and behavior when omitted. It provides contextual usage beyond schema descriptions.

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

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

The description starts with 'Read a raw source document's content and metadata', providing a clear verb and resource. It distinguishes from sibling tools like raw_ingest, raw_list, and raw_versions by specifying the read operation.

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

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

The description gives detailed pagination guidance per file format (PDF, PPTX, XLSX, DOCX/text), including how to use parameters like 'pages', 'sheet', 'offset', and 'limit'. It also advises pagination for large documents. However, it does not explicitly compare to sibling tools (e.g., when to use raw_read vs wiki_read), but the resource type difference is clear.

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

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

No annotations are provided, so the description carries the full burden. It mentions returning metadata and a 'latest' field but lacks details on permissions, rate limits, or whether it is read-only. This is adequate but not enhanced.

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 concise with two sentences that cover all necessary information without any fluff. It is well-structured and front-loaded with the core action.

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 simplicity of the tool (one parameter, no output schema), the description provides adequate context including the return fields (metadata and latest field). It could mention pagination or limits, but for a version listing tool, it is sufficiently complete.

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

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

The single parameter 'filename' has 100% schema coverage with a description. The tool description adds an example but does not introduce new semantics beyond what the schema already provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb (list), resource (versions of a raw file), and provides specific details like sorting by version number and marking the latest. It distinguishes itself from sibling tools such as raw_list or raw_read by focusing on version history.

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

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

The description implies use for listing versions given a base filename, but does not explicitly state when not to use it or compare with alternatives. However, the context of sibling tools makes the usage clear enough.

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

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

The description details behaviors for each action, such as creating directories, regenerating files, and auto-fixing issues. While it does not explicitly mention destructive potential or permissions, it gives sufficient context for expected outcomes.

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 organized with a clear introductory sentence and a bullet list of actions. It is relatively concise, though some action descriptions could be slightly trimmed without losing clarity.

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

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

Given the tool's complexity (multiple actions and parameters), the description covers each action's purpose and relevant parameters adequately. Without an output schema, it still describes expected outputs (e.g., config shows configuration, evidence-report returns a report).

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 100% schema coverage, the description adds significant value by explaining how each parameter modifies behavior (e.g., apply_fixes for lint, write for evidence-report, evidence_report and okf_report for rebuild). This goes beyond the schema's basic descriptions.

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

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

The description clearly states the tool's purpose as 'Wiki administration and maintenance' and enumerates specific actions (init, config, format-check, rebuild, lint, evidence-report), distinguishing it from sibling tools that handle read/write/ingest operations.

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

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

The description provides explicit guidance for each action, including parameters and effects. However, it does not explicitly state when not to use this tool or compare with alternatives, leaving some room for ambiguity.

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, and the description does not disclose behavioral traits such as irreversibility, permission requirements, or side effects of the deletion. For a destructive action, this is insufficient.

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 two sentences with no wasted words. Every sentence provides value: the action and a key constraint.

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

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

Despite the simplicity (1 param, no output schema), the description lacks crucial context for a delete tool: irreversibility, safety, or usage conditions. It is incomplete.

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

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

Schema coverage is 100% with a description for the 'page' parameter. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'delete' and the resource 'wiki page,' distinguishing it from siblings like wiki_read, wiki_write, and wiki_list. The action 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?

The description provides a constraint ('Cannot delete system pages') which implies alternative tools for those pages, but it does not explicitly state when to use this tool versus alternatives or provide positive usage guidance.

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

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

No annotations are provided, so the description carries the full burden. It correctly indicates the tool lists pages, but does not mention read-only behavior, pagination, or potential performance implications.

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 a single concise sentence with no wasted words, front-loading the primary action and optional filters.

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

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

The tool has no output schema, but the description does not specify what is returned (e.g., list of page titles or full content). Missing details on pagination or result set size, making it incomplete for an agent.

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 description repeats the filtering options. It adds no additional meaning beyond what the schema already provides.

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

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

The description clearly states 'List all wiki pages' with optional filters, which is specific and distinguishes from siblings like wiki_read (single page) and wiki_search (keyword search).

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

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

The description implies usage for listing pages but does not explicitly state when to use this tool over alternatives like wiki_search or wiki_read. No exclusions or context are provided.

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 fully assumes the burden of behavioral disclosure. It discloses truncation at 200 lines without a `section`, the presence of `truncated` and `toc` in the response, and the case-insensitive partial match for `section`. All key traits are transparently communicated.

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 concise with two well-structured paragraphs. The first paragraph states core functionality and the multi-page option; the second provides the recommended workflow. Every sentence adds value, and the information is front-loaded.

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

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

For a read tool with 5 optional parameters and no output schema, the description covers all essential behaviors: single/multi-page reads, section navigation, truncation, and line-based paging fallback. It also mentions response fields (`truncated`, `toc`), making it complete for an agent to use 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 each parameter is described in the schema. The tool description adds meaning beyond the schema by explaining the workflow (e.g., using `pages` to save round trips) and the behavioral context (e.g., truncation, section navigation). This adds significant value, moving beyond the baseline of 3.

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

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

Clearly states it reads wiki pages, distinguishes between single and multiple pages via `page` and `pages` parameters, and differentiates from sibling tools like `wiki_search` (search) and `wiki_write` (write). The verb "read" is specific, and the resource "wiki pages" is well-defined.

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

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

Provides an explicit recommended workflow (1-2-3) for navigating large pages using `wiki_search` and `section`. It also advises when to use `section` to avoid truncation and mentions the round-trip savings of the `pages` array. This gives clear context for using the tool vs alternatives.

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

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

With no annotations, the description fully discloses behavioral traits: default BM25, hybrid mode conditional on config and rebuild action, greedy inline_budget, deduplication in read_top_n, section case-insensitive partial match, and knowledge_gap return on no results.

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?

Well-structured with core purpose first, then detailed parameter explanations. Slightly long but each sentence adds value. Could be slightly more concise, but no wasted words.

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

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

Given 10 parameters and no output schema, description covers all parameters and important behaviors (hybrid mode, inline_budget, read_top_n, knowledge_gap). Agent can fully understand tool capabilities and make informed calls.

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% (baseline 3), but description adds value beyond schema: hybrid mode requires config and rebuild, inline_budget is greedy, read_top_n deduplicates and returns pages array, section is case-insensitive partial match, knowledge_gap field for no results.

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

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

The description clearly states it's a full-text keyword search across all wiki pages, returns paths, scores, snippets sorted by relevance. It distinguishes from siblings like wiki_list, wiki_read, and wiki_write by specifying its search functionality and the ability to combine search+read.

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

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

Provides explicit guidance on when to use hybrid search, include_content, read_top_n, and filtering by type/tags. Mentions handling no-results with knowledge_gap. Does not explicitly list when not to use, but context implies its primary role for searching, not listing or reading specific pages.

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 fully carries the burden. It discloses auto-management of timestamps, auto-routing of pages based on frontmatter, auto-linking with exceptions (code blocks, existing links, URLs), and states that wiki pages are MUTABLE. No contradictions.

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

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

The description is a single well-organized paragraph, front-loaded with the main action, then details. Every sentence is meaningful, no redundancy.

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

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

The description covers auto-routing and auto-linking behaviors thoroughly. It lacks explicit details on overwrite vs merge behavior when updating an existing page, but overall adequate for a write tool with no output schema.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value for the return_content parameter by explaining its purpose (eliminates follow-up call) and default. No additional detail needed for other parameters.

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

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

The description clearly states 'Create or update a wiki page' with specific resource (wiki page). It differentiates from sibling tools like wiki_read, wiki_delete, etc., and provides scope (page path relative to wiki/).

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

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

The description gives guidance on when to use return_content to avoid a follow-up wiki_read call, implying efficient workflows. It doesn't explicitly state when not to use this tool, but context from sibling tools is clear.

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