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

No annotations are provided, so the description carries the full behavioral burden. It discloses that returned content is Markdown and that pages may be Confluence or crawled external websites (useful scope context), but it says nothing about permissions/auth, pagination or truncation of long pages, caching interplay with refresh_cache, or error behavior for invalid IDs. Adequate but incomplete for a read tool with zero annotation coverage.

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?

Front-loaded with the action and return type, followed by one sentence of usage guidance and one short Args entry. No filler, 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?

An output schema exists, so the description needn't explain return values. It covers purpose, upstream tooling, content format, and page-type scope. The remaining gap is behavioral detail (permissions, truncation) that no annotation supplies, but for a simple single-param reader the description is 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?

Schema description coverage is 0%, so the description must compensate, and it does: it explains page_id is 'The page ID from search_pages or list_pages results,' telling the agent where the value originates. With only one parameter, this is close to complete; it lacks only format/length details, which are minor given the provenance guidance.

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?

Specific verb (Retrieve) plus resource (full Markdown content of a specific page by ID), and it distinguishes itself from siblings by naming search_pages and list_pages as the upstream producers of the ID. An agent can immediately tell this is the read-full-content step after a search/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 states when to use it: 'Use this after search_pages to read the complete content of a result.' It names the alternative workflow (search_pages/list_pages for discovery, this for full content), which is exactly the routing an agent needs.

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 behavioral burden. It usefully discloses that results come from a cache (implying possible staleness and a relationship to refresh_cache), but says nothing about pagination or result-size limits for a 'list all' operation, or any auth requirements.

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?

Front-loaded with the purpose in the first sentence and the argument explained immediately after; nothing extraneous. Minor redundancy in restating the space-key filter inside the Args block.

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 single-optional-parameter read tool with an output schema present, the essentials are covered. However, with no annotations the definition should at least declare the read-only nature and the cache-refresh relationship to its siblings, which it does not.

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 identify space_key as an optional filter, but that is essentially a restatement of the parameter name plus the already-implied optionality from default ""; no format, example, or matching behavior is added.

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 with a qualifying scope ('List all cached pages'), which also separates it from get_page and search_pages since it is a bulk cached listing. It never explicitly names or contrasts with those siblings, so an agent must infer the boundary itself.

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 word 'optionally' implies when the space_key filter applies, but there is no statement of when to prefer this over search_pages or get_page, and no exclusions or prerequisites. Usage is only implied.

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 behavioral burden, and it does disclose meaningful traits: it operates on ALL configured subtrees, it forces an immediate re-crawl, and it bypasses TTL and version checks. It does not state permission requirements, whether the call blocks until completion, or the cost/rate-limit implications of a full re-crawl, leaving real gaps.

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?

A single front-loaded sentence that names the action, the scope, and the bypass behavior with zero filler. Every clause 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 zero-parameter tool with an output schema present, the description need not explain return values, and it sufficiently conveys scope and effect. The only shortfall is the absence of auth/permission and synchronous-vs-async behavior for what is clearly an expensive forced refresh.

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 takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description adds no parameter context because none is needed.

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 ('Force an immediate re-crawl') and an exact resource scope ('all configured subtrees'), and the phrase 'bypassing TTL and version checks' distinguishes it from the read-only siblings (list_pages, search_pages, get_page). An agent can tell this is a cache-invalidation operation without opening any 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?

Usage is implied rather than stated: 'bypassing TTL and version checks' suggests this is for forcing freshness when cached data is unacceptable. However, there is no explicit when-to-use, when-not-to-use, or named alternative, so the agent must infer the trigger condition itself.

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 and does well: it discloses that only short snippets are returned, warns the snippet is a preview, and documents prefix matching plus the default and max limit. It does not mention cache staleness or whether refresh_cache is needed for fresh content.

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?

Front-loaded with the core behavior, then the actionable directive, then args. Slightly redundant, since 'Returns short snippets only' and 'The snippet is just a preview' make the same point, but nothing is 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?

An output schema exists so return values need not be explained, and the description covers purpose, follow-up workflow, and both parameters. The only gap is cache-related context (e.g., when results may be stale and what refresh_cache does), which matters for a cached-index 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%, and the description fully compensates: 'query' is defined as space-separated keywords with a single-key-term-first and prefix-matching strategy, and 'limit' gets default 10 / max 20. Both parameters gain meaning found nowhere 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?

States a specific verb and resource ('Full-text search across all cached Confluence pages and external links'), including the searchable scope, so an agent can distinguish it from get_page, which it explicitly names as the follow-up step.

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 a clear workflow directive ('Always call get_page on relevant results to read the full content before answering questions'), which is exactly the context an agent needs. It does not, however, explain when to prefer search_pages over siblings like list_pages or refresh_cache.

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