llmref

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

Annotations already indicate a safe read-only operation (readOnlyHint=true) and non-exhaustive results (openWorldHint=true). The description adds meaningful behavioral details: the query is 'forgiving fuzzy' over slugs with relevance ranking, and pagination uses limit/skip. This supplements the annotations without contradiction.

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 consists of two tightly packed sentences that cover purpose, usage guidance, and key features (fuzzy query, pagination). No redundant or extraneous information—every word contributes to agent understanding.

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 read-only list tool with good schema documentation and no output schema, the description is sufficiently complete. It explains the discovery role, query semantics, and pagination—leaving no critical gaps 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?

The input schema already provides full descriptions for all three parameters (100% coverage), including default values and the fuzzy query behavior. The description restates these details but does not add new semantic depth beyond what the schema offers, so a 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 it lists 'indexed documentation projects' and explicitly positions it as the first step to 'discover what's available.' This verb-resource combination is specific and distinct from sibling tools like list_versions, which focus on versions of individual projects.

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 advises to 'Use this first to discover what's available,' providing clear context for when this tool should be invoked. While it does not explicitly list when not to use it, the implied workflow (list projects first, then drill down with siblings) is evident from the tool names.

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 provide readOnlyHint and openWorldHint. The description adds minimal behavioral context beyond stating it lists versions. No details about caching, pagination, or limits are provided, but the annotations cover the safety profile adequately.

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 sentences, front-loaded with the action and then usage guidance. No unnecessary words, every sentence serves a purpose.

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 list tool with one well-documented parameter and annotations, the description is almost complete. It explains the purpose and usage. Lacking only explicit description of the output format, but since there is no output schema, the mention of 'valid version strings' provides sufficient expectation.

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

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

Schema coverage is 100% and the parameter description in the schema is clear. The tool description does not add any additional meaning 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 action (list available versions) and the resource (project). It also distinguishes from siblings by specifying that this tool should be called before resolve_docs or search_docs to obtain valid version strings.

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 states when to use the tool (before resolve_docs or search_docs) and implies its output is needed for those tools. However, it does not explicitly mention when not to use it or alternatives, which would make it a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety and open-world nature are covered. The description adds value by listing the returned artifact URLs but does not elaborate on error behavior or edge cases.

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: the first summarizes the action and output, the second provides usage guidance. No wasted words, front-loaded with essential information.

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 rich annotations and full schema coverage, the description adequately explains the output (artifact URLs) and use case. It lacks details on error handling but is otherwise complete for a resolve 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% with descriptions for both parameters. The tool description adds limited semantic value beyond what the schema provides, merely contextualizing the parameters with usage advice.

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 resolves a project version and returns artifact URLs, listing specific files (llms.txt, etc.). It distinguishes itself from sibling tools by explicitly referencing list_versions as a prerequisite.

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 advises using list_versions first to discover valid version strings, providing clear guidance on when to use this tool. It lacks explicit exclusionary guidance but is sufficient for context.

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, so the description does not need to cover safety. It adds that the tool returns chunks ranked by relevance, which provides slight behavioral context. However, it omits details on pagination, token budget behavior, or error scenarios, leaving gaps that a richer description could fill.

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 concise sentences that front-load the purpose and then state a key requirement. Every word adds value, with no redundancy or 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?

Given the tool has 5 parameters, no output schema, and functional siblings, the description covers the core purpose and a prerequisite. However, it lacks information about the return format (e.g., structure of chunks), how token_budget works, or how results are ordered beyond relevance. This incomplete context may hinder an agent's expectations.

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 descriptions for all 5 parameters with 100% coverage. The description does not add any parameter-specific guidance beyond what the schema offers, so it meets the baseline but does not enhance understanding of parameter usage or interaction.

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 performs semantic search across project documentation and returns chunks ranked by relevance. It distinguishes from sibling tools (list_projects, list_versions, resolve_docs) which handle data retrieval, version listing, and doc resolution, not full-text 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 explicitly requires the server to have semantic search enabled, giving a clear prerequisite. It implies this tool is for searching when you need semantically relevant chunks, but does not explicitly state when not to use it or name alternative tools for similar tasks.

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