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

Annotations already declare readOnlyHint=true, idempotentHint=true, so the agent knows it is safe and side-effect-free. The description adds that it pertains to 'cache and index status', which is useful but minimal. No hidden behaviors or side effects are disclosed, but given the annotations, the bar is lower and the description is consistent.

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 with no wasted words. It is appropriately sized for a parameterless tool with strong annotations.

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 simplicity (0 params), clear annotations, and the existence of an output schema, the minimal description is largely sufficient. It could mention the nature of the status (e.g., 'last updated time') but the output schema likely covers that. Overall, it meets the needs for a read-only diagnostic 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?

The input schema has no parameters (100% coverage), so the description does not need to add param details. Baseline 3 is appropriate as the description does not add meaning beyond what the schema 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 'Get cache and index status' clearly specifies the verb 'get' and the resource 'cache and index status'. It is distinct from sibling tools which focus on reading or searching content, but it does not explicitly differentiate itself from alternatives like search tools or refresh_docs.

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 the listed siblings (e.g., checking cache freshness before reading vs. searching or refreshing). The description gives no context about typical use cases or prerequisites.

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, idempotentHint=true, and openWorldHint=false. The description adds no new behavioral traits beyond 'inspect sections', which is consistent with these annotations. It does not disclose details like whether the tool returns heading levels, ordering, or that it only reads headings without content. With annotations covering the safety profile, the description adds minimal value.

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 of 10 words, very concise and front-loaded. It conveys the core purpose without unnecessary words. However, it could include a brief note about the parameter or output without sacrificing 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?

Given the tool is simple (1 parameter, no enums) and has an output schema, the description is incomplete. It does not mention that the output is a list of headings or any structure. The phrase 'before reading a chunk' hints at usage but doesn't explain what the tool returns. With annotations already covering read-only and idempotence, the description should clarify the output to be fully 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 input schema has one required parameter 'path' with no description (schema description coverage 0%). The description does not mention or explain the 'path' parameter at all. It says 'known page' but does not clarify how to specify the page (e.g., file path, ID). The description fails to compensate for the lack of schema documentation, leaving the parameter completely unspecified.

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 'Inspect sections within a known page before reading a chunk' clearly states the tool's function: listing headings/sections of a page. It distinguishes from sibling tools like 'read_section' (reads content) and 'search_within_page' (searches within page). The verb 'inspect' and noun 'sections' are specific, though the output format (e.g., list of headings) is not explicitly stated.

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 a workflow context ('before reading a chunk'), suggesting when to use the tool. However, it does not explicitly state when not to use it or mention alternatives like 'search_within_page' or 'list_pages'. No exclusions or comparisons are provided, leaving some 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?

Annotations already provide readOnlyHint=true and idempotentHint=true, but the description adds no behavioral information beyond what the annotations convey. It does not mention that the tool is read-only, idempotent, or describe any side effects, pagination, or ordering. The bar is lower due to annotations, but the description still fails to add value.

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, making it concise. However, it prioritizes the usage condition over the tool's purpose, which reduces clarity. It is not front-loaded with the core action. Every word should earn its place, but here the sentence sacrifices meaningful description for 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?

The tool has two optional parameters and an output schema, yet the description only gives a usage condition. It does not explain what the output contains (e.g., list of page titles, IDs, or metadata) or how to interpret results. Even with the output schema, the agent lacks context on the tool's purpose and behavior.

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 has two parameters (limit and prefix) with 0% description coverage. The description does not mention either parameter, their purpose, or how they affect results. Since coverage is low, the description must compensate, but it completely fails to explain parameter semantics.

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 'Discovery only when search does not identify a relevant page' is not a direct statement of what the tool does. It implies listing pages for discovery, but the purpose is not clearly stated as a verb+resource. The name 'list_pages' partly clarifies, but the description adds ambiguity by focusing on the condition rather than the action.

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 tells the agent when to use this tool: 'only when search does not identify a relevant page.' This provides clear context and contrasts with sibling tools like search_docs, establishing a fallback pattern. This is excellent 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?

Given annotations already declare readOnlyHint, idempotentHint true, and openWorldHint false, the description correctly implies a read-only, idempotent operation. The description adds value by specifying the conditional behavior ('when immediate neighbor refs are not enough'). No contradiction found.

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, relatively concise sentence. It efficiently introduces the tool's conditional nature. One could argue 'nearby' is redundant, making the sentence slightly less concise than ideal, but it's still effective and not verbose.

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?

An output schema exists, so the description doesn't need to detail return values. With 3 parameters (1 required), it's a simple tool. The description, combined with the schema, gives a minimally viable understanding of the tool's input/output. Missing mention of the 0-3 range for before/after is a minor gap.

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 0%, so the description must explain parameters. It effectively describes 'after' and 'before' implicitly through the concept of 'immediate neighbor refs' and 'expand nearby', but it does not mention the 'id' parameter or explain the numeric bounds of after/before (0-3). This forces the LLM to infer some meaning.

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 ('Expand nearby refs') and the resource ('chunk'). The purpose is discernible: this tool finds and returns the surrounding context around a specific position. However, it could better distinguish itself from siblings like 'read_section' by explaining what makes it different.

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 context ('when immediate neighbor refs are not enough'), setting an expectation of fallback behavior. However, it provides no negative guidance on when NOT to use this tool or how it differs from alternatives like 'read_section' or 'search_within_page'.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is clear. The description adds that the tool reads a single chunk with pagination, which is consistent with the hints and clarifies the paginated nature beyond what annotations provide. A minor deduction because the description doesn't mention any side effects or return structure, but overall it's very 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 two sentences, zero wasted words. The first sentence states the core function, the second provides strategic guidance. Every 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?

Given the annotations (readOnly, idempotent, openWorld), the presence of an output schema (handling return structure), and the clarity of purpose/usage, the description is nearly complete. The only gap is not explaining the parameter roles in detail, but the output schema likely covers return values. A score of 4 reflects that it's well-suited for a tool with good structural support.

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 0%, so the description must compensate. Although the description doesn't detail each parameter, it effectively implies the core usage (read a chunk, pagination) which orients the agent. For 4 parameters with no schema descriptions, this is adequate to infer most parameter purposes, though specifics like offset vs. segmentIndex aren't explained.

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 one chunk with pagination', which uses a specific verb and resource, and the context about preferring neighbors.before/after distinguishes it from sibling tools like search_docs or list_headings.

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 tells the agent when to use this tool ('prefer neighbors.before/after for the next local read before running another global search'), effectively contrasting it with alternatives and providing a clear usage strategy.

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 indicate non-readOnly, non-idempotent, and non-destructive behavior, but the description fails to explain what 'refresh' entails—whether it reprocesses all documents, deletes cache, or affects user queries. For a mutation without idempotency, the agent needs to know if repeated calls cause errors or performance degradation.

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 extremely short at six words, which aids quick scanning. However, it is under-specified—every sentence should earn its place, but here the brevity sacrifices clarity. A slight expansion to 1-2 sentences would maintain conciseness while improving value.

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, return values need not be explained, but the tool has moderate complexity (rebuild operation without idempotency) and siblings like get_status for index state. The description is incomplete—it fails to specify the effect on existing index data, whether the operation is synchronous or async, and what happens to in-flight queries.

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 0% schema description coverage and only one parameter (force), the description omits all parameter meaning. A description like 'force boolean: if true, bypass incremental refresh and do a full rebuild' would add significant value, but currently the agent must infer meaning from the name alone.

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 specific actions (refresh, rebuild) and a resource (source docs, index), establishing a clear purpose. However, it does not differentiate from sibling tools like get_status, which might also involve index state, missing a chance to clarify the tool's distinct role.

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 no guidance on when to use this tool versus alternatives, such as when a simple refresh is appropriate versus when to rebuild from scratch. It does not mention prerequisites (e.g., requiring recent document changes) or potential side effects, leaving the agent without decision-making support.

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 idempotentHint=true, covering the safety profile. The description adds behavioral guidance to switch to local navigation after finding a page, which provides useful context beyond annotations. It doesn't describe return format, but an output schema exists.

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 'Start here', and every word adds value. There is no redundancy or 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 provides the essential workflow (global search first, then local navigation) and the output schema covers return values. The missing parameter semantics is a small gap, but the overall context is sufficient for a straightforward search 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 description coverage is 0%, so the description must compensate for parameter meaning. However, the description does not mention query, limit, or offset at all, leaving the agent to infer their semantics solely from parameter names and 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 states 'global docs search', which clearly identifies the tool as a search across all documentation. The phrase 'Start here' positions it as the entry point, differentiating it from sibling tools like search_within_page and read_section.

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 'Start here' and instructs to 'prefer local navigation over another global search' once a relevant page is found. This gives clear when-to-use and when-not-to-use guidance, naming the alternative approach (local navigation).

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, idempotentHint=true, and openWorldHint=false, so the safety and idempotence are clear. The description adds behavioral context ('after global search') that clarifies the tool's position in the workflow. No negatives are omitted, and no contradiction exists.

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 short sentences. The first sentence front-loads the core purpose, the second adds the key usage guideline. No redundancy or 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?

Despite concise purpose and guidelines, the description lacks detail about required behavior (e.g., what happens if path is invalid), parameter constraints (limit max 4, offset max 500), and relationship to siblings like 'list_headings' or 'read_section'. An output schema exists but the description does not leverage it to set 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?

Schema description coverage is 0%, so the description must compensate. It does not explain any of the four parameters (path, query, limit, offset). The agent gets no additional meaning beyond parameter names and types, which is insufficient for correct usage.

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 'Narrow within a known page after global search' uses a specific verb ('narrow') and clearly identifies the resource ('page'). It distinguishes this tool from the sibling 'search_docs' (global search) by framing it as a follow-up refinement.

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 phrase 'Prefer this over another global search' provides explicit guidance: after a global search, use this to narrow within a known page instead of re-running a broad search. It does not name the alternative sibling but implies it (likely 'search_docs'). Missing explicit when-not-to-use or prerequisite conditions.

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