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

With no annotations, the description discloses useful behavioral details: definitions are listed first, then declarations/references, and each result appears as 'path:line: code'. This adds context beyond basic purpose, though it does not mention edge cases like not-found behavior or output limits beyond what schema provides.

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 main verb and resource, and includes an output format example. Every word contributes value; 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?

The description covers purpose, result ordering, and output format, which is sufficient for a simple search tool with a well-defined schema and no output schema. It lacks an explicit mention of alternatives or edge cases, but the core information needed to use the tool is present.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific meaning beyond the schema, but the schema already documents all parameters (symbol, max_results, path_filter) with examples and bounds.

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

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

The description uses a specific verb ('Locate') and resource ('function, struct, macro, typedef, or variable across the 4.2BSD source'), making the tool's function unambiguous. It also differentiates from siblings like search_source by focusing on symbol lookup and mentioning result ordering.

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 symbol lookup, but does not explicitly state when to prefer this over sibling tools like search_source or search_all, nor does it provide when-not or alternative guidance. The context is clear but lacks explicit usage boundaries.

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 burden of disclosure. It specifies that the tool returns metadata plus a page-by-page overview (first line of each page), which accurately conveys the behavior and implies a read-only operation. It does not detail what metadata fields are included, but for a simple read tool this is reasonably 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 a single, well-structured sentence that front-loads the action ('Return metadata'), specifies the resource and output format, and ends with a practical use case. Every part earns its place with 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 low complexity (one parameter, no output schema), the description provides sufficient context about what the tool returns and when to use it. It could specify metadata fields or output structure in more detail, but for selection and invocation the current description is complete enough.

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 fully documents the single parameter doc_id, including an enum of allowed values and an example description. Since schema description coverage is 100%, the description adds no additional parameter semantics, and the baseline score of 3 applies.

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

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

The description clearly states the tool returns metadata for one document plus a page-by-page overview consisting of the first line of each page. This distinguishes it from siblings like list_documents (listing) and read_pages (reading full content) by highlighting its role as a table-of-contents summary.

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 frames the tool as useful as a table of contents before reading specific pages, giving a clear when-to-use context. It does not name alternative tools or explicitly state when not to use it, but the use case is sufficiently implied relative to siblings like read_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 carries the full burden. It discloses the return behavior ('Returns its number, name, and any notes') and implies a read-only operation via 'Look up.' While it doesn't explicitly say 'does not modify anything,' the verb and return-value statement are sufficient for a simple lookup. It does not mention error handling or edge cases, but these are not critical for this level of transparency.

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 starts with the verb, gives examples, and states what is returned. Every part is necessary and informative, with no wasted words. This is exemplary conciseness.

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 simple one-parameter lookup tool with no output schema, the description fully covers the necessary context: what it does, how to invoke it (with examples), and what it returns. It also specifies the system call version (4.2BSD), which adds important scope. There is no missing critical information for the agent to select and invoke 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?

The schema already fully describes the parameter (100% coverage), so the baseline is 3. The description adds value by providing concrete examples ('2' or 'fork') and clarifying that both numeric and named lookups are supported, which reinforces the schema's description. This enrichment justifies a score above 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 clearly states the tool's function: 'Look up a 4.2BSD system call by number or name.' It gives concrete examples and specifies the resource (system call) and the action (look up). This distinguishes it from sibling tools like list_syscalls, which lists all syscalls rather than retrieving one.

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 this tool: when you have a specific system call number or name to look up. It doesn't explicitly mention alternatives like list_syscalls for enumeration, but the context is clear from the wording and examples. There are no exclusions provided, so it falls short of the explicit alternative guidance at score 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. It discloses the scope (historical UNIX documents on the server) and the metadata fields returned, but it does not explicitly mention read-only behavior, pagination, limits, or ordering. The word 'List' implies a non-mutating operation, but more transparency would be beneficial.

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, front-loaded sentence that states the action ('List') and the resource ('historical UNIX documents available on this server'), followed by relevant metadata fields. No redundant or vague language exists.

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 simple no-parameter listing tool, the description adequately covers the resource scope and return metadata. It could mention whether all documents are returned or if pagination is involved, but the simplicity and clarity of the operation make it nearly complete.

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

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

The tool has zero parameters and an empty schema. Since there are no parameters to describe, the baseline of 4 applies. The description adds no parameter-specific information, but nothing is needed in this case.

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 historical UNIX documents with specific metadata fields (title, authors, source URL, page count, description). This verb+resource pair is distinct from sibling tools like search_documents (search vs. list) and list_manpages (manpages vs. documents).

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 when you want an overview of all ingested documents, but it does not explicitly mention alternatives or exclusions. Sibling tools such as search_documents or get_document_info are not referenced, leaving the usage guidance to inference from the tool name and description.

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 explicitly states a read-only listing operation and defines the section semantics, but does not disclose other behavioral traits like authentication needs, rate limits, or return format. This is acceptable for a simple list operation but not exhaustive.

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

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

The description is a single, concise sentence that front-loads the main purpose. The parenthetical listing section meanings is dense but necessary and does not waste words. It is appropriately sized for the tool's simplicity.

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 simple listing tool with detailed schema documentation, the description covers the essential resource and filtering options. It omits explicit mention of return structure or ordering, but those are not critical for a list operation. It is sufficiently complete for an agent to select and invoke the 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?

The schema already describes both parameters (limit and section) with 100% coverage. The description adds significant semantic value by mapping each section enum value to its meaning (e.g., 1=commands, 2=syscalls), which the schema does not provide. This enrichment justifies a score above 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 clearly states the action ('List'), the resource ('4.2BSD manual pages'), and the optional filtering by section. It distinguishes itself from siblings like list_documents and list_syscalls by specifying the exact resource type.

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 provides clear context for when to use the tool by describing optional section filtering and explaining what each section means. However, it does not explicitly mention when not to use it or offer alternatives such as search_manpages, so it falls 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 must carry behavioral disclosure. It discloses that the output includes number, name, and notes, and that filtering is by substring. However, it does not mention output format, case sensitivity, or explicitly confirm it is a read-only operation, leaving some gaps for a simple listing 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 a single sentence that is front-loaded with the action and includes only necessary information. No waste 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 simple one-parameter listing tool with no output schema, the description is sufficiently complete: it states what is listed and the optional filtering. It does not cover alternatives or edge cases, but the tool's simplicity makes this acceptable.

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 description's 'filter by name substring' essentially mirrors the schema's parameter description ('Only show syscalls whose name contains this substring'). With schema description coverage at 100%, the description adds no new parameter semantics beyond the baseline.

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

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

The description clearly states the tool lists the 4.2BSD syscall table with number, name, and notes, and optionally filters by name substring. It does not explicitly distinguish from sibling tools like get_syscall, but the action and resource are specific enough.

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 syscalls and mentions an optional filter, but provides no explicit guidance on when to use this tool vs alternatives like get_syscall or search_all. No exclusions or alternative recommendations are given.

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 states that the tool returns the full text of exactly one page, and explains the ambiguity resolution behavior. This is transparent for a read-only tool, though it does not mention error cases or output formatting.

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 exceptionally concise: two sentences, front-loaded with the core action, and each clause earns its place. The example and ambiguity note are efficient and useful 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?

For a simple read tool with two parameters and no output schema, the description is complete enough for an agent to invoke it correctly. It covers name, optional section, and ambiguity resolution. It could mention what happens when the page is not found, but that is a minor omission.

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%, establishing a baseline of 3. The description adds meaningful guidance beyond the schema by giving a concrete example ('name="read", section="2"') and by explaining when the optional section parameter should be supplied due to ambiguity.

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 verb and resource: 'Read the full text of one 4.2BSD manual page by name and optional section.' This distinguishes it from sibling tools like list_manpages or search_manpages, which list or search rather than read a specific page.

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 clear context for use, including how to disambiguate when a name exists across sections ('If the name is ambiguous across sections, give the section'). It does not explicitly name alternatives or exclusions, but the context is sufficiently 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, the description carries the burden of behavioral disclosure. It discloses the read-only nature and the 'raw text' output, and clarifies range behavior. However, it does not mention error handling, page indexing (1-based), or what happens with out-of-range pages, though the schema partially covers the parameter constraints.

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 concise sentences, front-loaded with the primary action. The first sentence states the purpose, the second gives a usage guideline. Zero 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?

For a simple read tool, the description covers the core purpose and a key prerequisite. It lacks details on return format and edge cases, but 'raw text' implies the output. Given no output schema, this is reasonably complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds the concept of a contiguous range, complementing the end_page omit behavior, but does not provide substantial new meaning beyond what the schema already documents.

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 reads raw text of one page or a contiguous range of pages from a document. It uses a specific verb (read) and resource (document pages), effectively distinguishing it from sibling tools like read_manpage and read_source_file.

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 explicitly instructs to use get_document_info first to find the right pages, providing clear sequencing. It does not mention alternatives or exclusions, but the context implies this is the tool for reading document pages, not other document types.

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 burden of disclosing behavior. It explicitly states the 1500-line maximum and optional line-range limiting, which are important operational traits. Error behavior for missing files is not covered, but this is a minor gap for a simple read 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 two sentences long, front-loaded with the core purpose and examples, and contains no redundant information. Every word 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 simple file-reading tool with clear schema and no output schema, the description provides enough context: what it reads, examples, and output limits. It doesn't explicitly describe the return format, but that is implied and not critical for a read operation.

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 describes all three parameters with examples for 'path'. The description adds a general 'line range' hint and the 1500-line limit, but does not add significant semantic detail beyond the schema. Baseline 3 is appropriate for 100% schema coverage.

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 ('Read') and resource ('source file from the 4.2BSD tree') with concrete path examples. This clearly distinguishes the tool from siblings like read_manpage or read_pages.

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 tool's intended use is clear from the description and name. It provides practical usage context (line range restriction, 1500-line cap) but does not explicitly mention when to prefer this over alternatives like search_source or read_manpage.

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 of behavioral disclosure. It adds useful context by stating results are 'grouped by kind and labeled,' but it does not explicitly mention the read-only nature, result ordering, or potential limitations beyond what the schema covers.

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 at two sentences with no redundant phrases. It front-loads the action and scope, then adds a relevant detail about output grouping, making every word earn 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 simple search tool, the description covers the essential aspects: what is searched and how results are presented. While an output schema is absent, the description could include more structural details about results, but it is sufficient for correct tool selection and invocation, especially given sibling context.

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 schema covers 100% of the parameters with detailed descriptions (query and max_results), so the tool description need not add parameter semantics. The description adds no extra parameter detail, and the baseline of 3 is appropriate since the schema does the heavy lifting.

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

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

The description clearly states the action (search) and the resource (all corpora), enumerating the specific document types. It distinguishes itself from sibling search tools by emphasizing 'at once' and listing all three corpora, making its scope 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 communicates the primary use case: searching across every corpus simultaneously, which implies its use for broad queries. It provides clear context but does not explicitly state when to prefer individual search tools or exclude this tool for single-corpus searches.

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 burden of explaining behavior. It discloses the output ('ranked page-level matches with a snippet') and the optional restriction, which is meaningful for a search tool. It does not mention quirks like result limits or error handling, but those are adequately covered by the 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?

The description is two sentences, front-loaded with the core purpose, and every detail earns its place. It avoids redundancy and clearly conveys the essential behavior without unnecessary fluff.

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 simple search tool with a rich input schema, the description explains the return format sufficiently, especially given no output schema. It could mention default max_results or pagination behavior, but the schema already provides max_results details, making this adequately complete.

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

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

Schema description coverage is 100% with detailed parameter descriptions, so the baseline is 3. The description's mention of doc_id adds no new meaning beyond the schema's 'Restrict search to this document'; it offers no additional semantic insight for query or max_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 identifies the tool with a specific verb ('Search'), a precise resource ('ingested UNIX documentation'), and output details ('ranked page-level matches with a snippet'). It distinguishes itself from sibling tools like search_manpages and search_source by focusing on documents and the optional doc_id restriction.

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 provides clear context that this is for searching ingested UNIX documentation, and the optional doc_id clarifies a specific use case. However, it does not explicitly mention alternatives like search_manpages or search_source, so guidance is clear but lacks explicit exclusion.

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 behavioral burden. It discloses that results are ranked and include a snippet around the first hit, which gives some transparency. However, it does not mention behavior such as default result count, ordering specifics, or empty-result handling. For a simple read-only search tool, this is acceptable but not rich.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence contributes useful information. It includes the result format and parameter usage without fluff, achieving maximum conciseness.

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 straightforward search tool with a simple schema and no output schema, the description adequately covers purpose, result format, and key parameter semantics. It lacks an explicit mention of alternative tools, but the sibling list and clear naming make the scope obvious. A more detailed note on return value structure or pagination might be nice, but is not essential for this level of complexity.

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 schema covers 100% of parameters, so the baseline is 3. The description adds value beyond the schema by explaining the numeric section meanings (2=syscalls, 3=libc, etc.), which is not in the schema's enum descriptions. It also clarifies that the snippet is around the first hit, which relates to query interpretation. This extra guidance justifies a 4.

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 searches the 4.2BSD manual pages and returns ranked matches with snippets. This distinguishes it from siblings like search_documents (general documents) and search_source (source code), while also contrasting with read_manpage (reading a full page). The verb 'search' and resource are specific and 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 clear context: it is for searching manual pages, and the section restriction guidance (e.g., 2=syscalls, 3=libc) is helpful. It does not explicitly reference alternative tools or state when not to use it, but the naming and content implicitly differentiate it from sibling search tools. A brief note about using search_source for source code would earn a 5, but the current guidance is adequate.

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 discloses the output format (grep-style) and the filtering option, but does not specify search semantics such as whether regex is supported, case sensitivity, or behavior when no matches are found. The read-only nature is implied by 'Search', but not explicitly stated, leaving some ambiguity.

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 primary purpose and output format in the first sentence, and a concise optional-filter hint in the second. Every word serves a purpose, with no redundancy or fluff. It is an excellent model of brevity.

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 simple search tool with 3 parameters, no output schema, and no annotations, the description covers the essential aspects: scope, return format, and optional filtering. It could be more complete by noting edge cases like no-result behavior or search semantics, but given the simplicity, it is largely adequate. The absence of an output schema makes the explicit return format description important, and it is provided.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal value beyond the schema, only providing concrete examples for path_filter. The query and max_results are not further elaborated, so the description does not significantly enhance parameter understanding beyond the baseline.

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

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

The description clearly states the tool searches '4.2BSD kernel and userland C source' and specifies the output format as 'path:line: code'. This distinguishes it from sibling tools like search_documents or search_manpages, which target different corpora. The verb 'Search' and resource are explicit.

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 a clear context of use ('Search the 4.2BSD kernel and userland C source') and provides a practical filtering tip with examples ('netinet' or 'libc/gen'). However, it does not explicitly mention when to prefer this tool over alternatives like find_symbol or search_all, nor does it state exclusions. This is a clear context with no exclusions, warranting a 4.

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