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

With no annotations supplied, the description carries the full disclosure burden, and it does the important part: it defines corpus scope and hard limits on what will be searched. It also implies results carry ids (since get_doc consumes them), but never describes result shape, ranking behavior, or what happens when a query matches nothing. A minor gap, not a misleading one.

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

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

Three sentences, front-loaded with purpose, then boundary, then routing. The source enumeration is long but earns its space by telling the agent exactly what corpus it will hit. No filler or restatement of the name.

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

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

For a 3-parameter read tool with no output schema, the description covers purpose, scope, and sibling routing thoroughly. The remaining omissions — result format and the meaning of limit — are modest, since there is no output schema to explain returns and the schema covers two of three parameters.

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 67% — query and source_types are documented in-schema, while limit (default 6, max 15) is undocumented anywhere. The description adds no parameter-level meaning at all: it never mentions source_types filtering or result count. Baseline 3 is appropriate since the schema does most of the work, but the description misses an easy chance to explain narrowing by source type.

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

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

States a specific verb and resource ('Semantic (meaning-based) search over the NEAR knowledge base') and enumerates the corpora covered (docs.near.org, gov.near.org, release notes, blog, ecosystem catalog, GitHub issues). It also draws a hard boundary ('NEAR only: not for other blockchains, the general web or local files'), which lets an agent separate it from the generic 'search' sibling without opening either schema.

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

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

Gives explicit when-to-use ('conceptual how-does-X-work questions') and names two alternatives with the condition selecting each: 'search' for exact-term or name lookups, and 'get_doc' to read a full page once an id is known. Exclusions for non-NEAR content are stated outright, so routing decisions require no inference.

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