boardrepo

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds meaningful behavioral specifics beyond annotations: bounded README excerpt, detected KiCad version, capability flags, and the instruction not to invent a board. This is useful context without contradicting the 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?

Three sentences cover usage triggers, return contents, and routing to sibling tools with no filler. The structure front-loads the when-to-use condition and each sentence 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?

The description is complete for an agent to select and call the tool: it gives input forms, output categories, discovery method, and follow-up tool routing. The output schema covers the detailed return structure, so no critical information 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 schema description already covers the parameter at 100%, including the accepted input forms and the 'search_boards' discovery route. The description mostly restates this guidance, adding only the 'do not invent one' caution, so it adds little beyond the schema 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 names a specific verb and resource ('Returns its metadata, a bounded README excerpt, tags, license, source EDA format...') and clearly distinguishes from siblings by directing design-detail needs to read_schematic, get_bom, or list_board_files. This is a clear, non-tautological definition.

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 first sentence states explicit trigger conditions: when the user names a specific public board, gives a URL, or picks a search_boards result. It also provides alternatives for follow-up actions ('chain to read_schematic...'), making the choice boundary 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 mark the tool read-only, idempotent, and non-destructive. The description adds substantial behavioral context beyond that: pagination limit of 200 lines with cursor continuation, performance cost of enabling pricing, and the caveat that pricing may be partial or absent for obscure parts. It also states what the tool does not return (device pinouts). No contradiction with 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?

Four sentences, each earning its place: the primary use case is first, followed by pagination behavior, pricing behavior, and then exclusions/alternatives. There is zero filler or repetition of schema fields. The most decision-relevant guidance 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-only list tool with three parameters, full schema coverage, an output schema, and rich annotations, the description covers all essential calling contexts: main purpose, pagination, optional pricing behavior, board discovery, and related tools for other intents. Nothing an agent needs to select and invoke this tool correctly is missing.

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

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

Schema description coverage is 100%, so the description needs little additional parameter explanation. It subtly reinforces the cursor usage ('pass the returned cursor for more') and references include_pricing's cost/availability trigger, but these are already covered in the schema. The description adds no new parameter-level meaning beyond the schema, which matches the baseline for full 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 and resource ('get a public board's BOM') and enumerates exactly what the BOM includes (reference designators, quantity, value, footprint, MPN, manufacturer, DNP, datasheet). It distinguishes itself from read_schematic by explicitly excluding pinouts and routing how-parts-connect questions to that sibling.

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 opens with a clear when-to-use trigger ('when the user asks which parts a public board uses'). It gives explicit guidance for the include_pricing parameter (when cost/sourcing/availability is requested) and routes ambiguous board requests to search first. It also names read_schematic as the alternative for connectivity questions, covering when-not-to-use.

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 mark the tool read-only, idempotent, open-world, and non-destructive, and the description adds important behavior beyond that: results are stored rather than freshly computed, waived rules were never evaluated and are listed separately, and an unrun result is explicitly not a pass. This substantially helps an agent interpret the response correctly.

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 compact, front-loaded with the primary use case, and every sentence adds signal: when to use it, what it returns, how waived rules behave, and the critical caveat that 'not run' is not equivalent to passing. There is no filler or repetition.

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 five-parameter schema with complete descriptions, an output schema, and safety annotations, the description covers all the contextual information an agent needs: when to select the tool, how to interpret results, and how to avoid confusing missing checks with a pass. No important behavioral gaps remain.

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

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

Schema description coverage is 100%, so all five parameters—board, rules, cursor, vendor, and category—are already documented in the schema. The description adds general output context such as paged example violations and per-category counts, but it does not need to compensate for schema gaps, 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 names a specific operation—returning stored DRC and ERC results for a board's current version—and lists the categories covered (design rules, unconnected copper, parity, ERC). It distinguishes itself from a design review and implies it is not running checks, making its purpose 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?

It gives explicit entry conditions: use when the user asks whether a board passes KiCad's own checks, or before trusting a design. It also sets boundaries, noting it is not a design review and that a 'checks not run' result is not the same as passing, though it does not explicitly name sibling tools like run_checks or review_board as 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?

The description adds meaningful behavior beyond the readOnlyHint and idempotentHint annotations: it returns up to 100 items per call, supports an opaque cursor for pagination, and explicitly states it returns paths only, never file contents. No contradiction with 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 compact, front-loaded with the core use case, and every sentence adds value: when to use, what it returns, pagination, and what to prefer instead. No filler 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?

Given the output schema, annotations, and sibling tool context, the description is complete. It tells the agent how to find a board, what results to expect, how pagination works, and which alternative tools to prefer for specific needs.

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 fully documents both 'board' and 'cursor'. The description adds a small amount of operational context around the cursor ('pass the returned cursor only when more are needed') but does not need to compensate for missing schema documentation.

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 action and resource: listing the exact files in a known public board. It also clarifies what the tool returns (paths, extensions, sizes, roles) and distinguishes it from siblings like read_file, read_schematic, and get_bom.

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 says when to use this tool ('before read_file, or to show a project's layout'), when not to guess paths, and directs users to read_schematic for wiring and get_bom for parts. It also explains pagination usage with the cursor.

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 behavior. The description adds meaningful behavioral context: takes no board, layer coverage is per profile and not interchangeable, and get_checks reports unsupported cases rather than guessing. No contradiction with 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 front-loaded with the primary use case and completes with concise caveats that directly affect correct usage. Every sentence contributes either routing, scope, or a caution; there is no filler.

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

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

The description fully covers what the agent needs to use the tool correctly: when to call it, what it returns conceptually, why layer coverage matters, and what not to do. The output schema handles return-structure details, so no critical behavioral information 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 has zero parameters and the schema already reflects that with 100% coverage. The description reinforces the invocation context by saying 'Takes no board,' which is useful grounding even though there are no parameters 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?

States a specific action ('list') on a clear resource ('fab profiles') and names the intended use with get_checks. It distinguishes itself by explaining it shows which fab houses and their limits, not just a generic list.

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 instructs to use before get_checks(vendor: ...) and warns not to invent a vendor id. It provides clear when-to-use context but does not explicitly describe when-not-to-use or discuss alternatives beyond the get_checks tie-in.

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 behavior. The description adds value by explaining that the tool interprets the file structurally, returns matching nodes as data, and is cheaper and more reliable than reading large board files as text. This gives a useful behavioral model beyond the 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 compact and well-structured: it states the core purpose first, then gives examples, then routes users away from sibling tools. Every sentence contributes useful decision-making or invocation guidance with no filler.

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

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

Given the rich input schema, output schema, and strong annotations, the description covers the tool's role, usage context, alternatives, and example selects. Nothing critical is missing for an agent to decide when and how to invoke it.

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 documents all parameters at 100% coverage, so the baseline is 3. The description adds meaningful semantic context by telling users to obtain the file path from list_board_files and by giving realistic select-path examples for layers, footprints, symbols, and net classes.

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 a KiCad file as structured data rather than raw text, with a specific verb and resource. It provides multiple concrete examples for different file types, which makes its purpose immediately distinguishable from siblings like read_file and read_schematic.

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

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

It gives explicit when-to-use guidance: when you need structure, not text, and when you already have a file path from list_board_files. It also names alternatives directly—read_file for raw text, read_schematic for connectivity—and says to prefer this when the netlist does not carry the information.

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 readOnly/idempotent annotations, the description discloses critical behavior: text files return a 128 KiB UTF-8 chunk requiring nextOffset pagination, binary files return a download URL rather than bytes, and the agent must not claim to have read binary contents. This is valuable operational context not implied by the schema or 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?

Every sentence earns its place: use case, return behavior for text and binary, path constraint, and sibling routing. It is front-loaded with the core purpose and contains no filler.

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

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

With no output schema, the description fully covers return semantics, pagination, binary handling, and usage boundaries. It also includes guidance about using read_schematic for circuit understanding, making the tool contextually complete for correct invocation.

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 meaningful semantics by tying path to list_board_files, emphasizing that paths must not be guessed, and explaining that offset accepts the returned nextOffset for continuation.

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'), a precise resource ('raw contents of a specific file in a public board'), and constrained inputs ('exact path from list_board_files'). It also distinguishes itself from siblings by explicitly excluding raw .kicad_sch parsing in favor of read_schematic.

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 says when to use the tool: when the user wants raw file contents by an exact path. It gives clear exclusions ('Do not guess paths') and directs the agent to read_schematic for understanding circuit wiring, providing a concrete alternative.

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 and openWorldHint=true, and the description adds valuable non-obvious behavior beyond those: the results are geometry-free in-design connections rather than an authoritative manufacturer pinout, large designs may be truncated with a flag, and nets may still be computing so the agent should not infer connectivity. No contradiction with 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 front-loaded with the usage trigger and every sentence adds operational value: output modes, caveats about truncation and manufacturer pinouts, preference guidance, and sibling routing. It is dense but well structured and contains no filler.

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

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

Given the output schema exists and annotations cover safety, the description is complete: it explains when to use the tool, how each mode changes the response, what to do while nets are computing, and which sibling tools cover other intents. An agent has everything needed to select and 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?

Although schema coverage is 100%, the description adds meaning beyond the schema by explaining each parameter's return shape: ref returns a component plus its nets and connected pins, net returns the pins on that net, and no focus returns a bounded overview. It also reinforces the 'at most one of ref or net' constraint and gives concrete examples like U1 and GND.

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 a public board's connectivity: how it is wired, component connections, and net pins. It distinguishes itself from siblings by explicitly routing purchasing questions to get_bom and raw source questions to read_file, and by differentiating overview, ref, and net outputs.

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 opens with a concrete trigger: 'Use when the user asks how a public board is wired, what a component connects to, or which pins are on a net.' It also provides explicit exclusions and alternatives, such as 'Use get_bom for purchasing and read_file for raw source,' and advises preferring focused ref or net queries over repeated overviews.

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 readOnlyHint/openWorldHint annotations, the description discloses that this is an expensive shared real kicad-cli run, that it can return status 'running' on a busy queue, that results should later be read via get_checks, and that custom rules results are never stored as if published by a fab. These are significant behavioral details the annotations do not convey.

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 economically written, front-loading the triggering condition and the core action before diving into cost and edge-case behavior. Every sentence adds distinct value: use condition, what it runs, cost/shared nature, possible async result, and an explicit exclusion.

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 an output schema and three parameters, the description covers the invocation trigger, alternative tools, async behavior, cost implications, and parameter relationships. Nothing needed for correct selection or invocation is missing.

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

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

Even though the schema already documents all parameters, the description adds meaningful semantics: vendor id must come from list_fab_profiles, rules are custom in-house limits expressed in millimetres, and rules and vendor are mutually exclusive. It also explains the storage implication of custom rules, which is not present 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 opens with a concrete verb-resource pair ('Runs KiCad's own DRC and ERC') and immediately distinguishes the tool from get_checks by stating it is for when checks have not yet been run. It also clarifies the optional fab-house variant, making the purpose unmistakable even among many sibling 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?

It explicitly says when to use the tool ('when get_checks reports the checks have not been run... and you need a verdict') and when not to use it ('Do not use it to re-run a board that already has a result'). It also gives cost-aware guidance, telling the agent to avoid running it on every board, and references list_fab_profiles as the source for vendor ids.

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 mark the tool as read-only, idempotent, and non-destructive, and the description adds meaningful behavioral detail beyond them: matching is literal and case-insensitive, not a regular expression, and results include file, line number, and matching line. It also clarifies the optional path_suffix restriction, giving the agent a precise model of how the search behaves.

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 three dense sentences with no filler: it states the action and benefit, defines matching behavior and options, and closes with routing to alternatives. Every sentence adds information an agent needs, and the key purpose 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 four-parameter search tool with a full output schema and safety annotations, the description is complete: it explains board discovery, query semantics, optional filtering, and the exact return shape. It also covers sibling differentiation, leaving no obvious gap 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?

Schema description coverage is 100%, so the baseline is 3, but the description enriches parameter meaning with concrete query examples ('USB_DP', 'ATmega328'), explicit literal-search semantics, and an example path_suffix ('.kicad_sch' or '.md'). This goes beyond the schema's property descriptions without having to restate them.

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 where something appears across a board's text files' in one call, with concrete examples of search targets and the returned fields (file, line number, matching line). It also explicitly distinguishes itself from siblings read_schematic and query_design, making the tool's role unmistakable.

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 clear when-to-use guidance: use it to locate a literal string across a board's files instead of reading files one by one. It also provides explicit exclusions and alternatives: 'Prefer read_schematic for how a design is wired and query_design for a file's structure; use this when you need to locate something by name.'

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 mark read-only/idempotent, and the description adds default ranking, pagination cap of 20, ANDed free-text semantics, qualifier syntax, and a caveat to weigh results by saves/stars. No contradiction with 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 front-loaded with the use case, then output/behavior, query semantics, and strategy. Every sentence adds distinct value, and the organization matches an agent's decision flow. Slightly dense but not padded.

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 rich input schema and existing output schema, the description covers pagination, sorting, qualifiers, defaults, and edge-case handling (empty results). Nothing an agent needs to invoke 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?

Although the schema has 100% coverage, the description adds substantial meaning: qualifier syntax (component:, tag:, license:, has:, author:), AND semantics, the 6-word limit, and a search optimization strategy ('cut straight to the SINGLE most distinctive term'). This goes far beyond the schema description.

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 clear verb ('Searches') and resource (BoardRepo's public corpus), and specifies the project types and returned fields. However, it does not explicitly differentiate from the sibling 'search_board', so the agent must infer the plural/scope distinction.

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?

Opens with an explicit 'Use when...' and describes the intended user goal, and it gives a concrete query strategy for handling empty results. It stops short of naming alternatives or when-not conditions, so it is clear context but no exclusions.

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