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

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds behavioral context beyond those flags: the operation persists a local configuration, indexes documents, makes the KB 'available immediately', and 'survives restarts'. Persistence/availability traits are genuinely useful and not in 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 tight sentences, front-loaded with the triggering condition, then the call constraint, then the outcome. No filler. Slightly telegraphic ('identical patterns') but 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?

No output schema exists, and annotations cover the safety profile, so the description needn't restate safety. It adequately covers the workflow, the persistence guarantee, and the preview-scope constraint. The main residual gap is the undocumented parameter set, which is a schema issue more than a description incompleteness.

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 carries the full burden. It adds meaning to preview_id and the include/exclude patterns ('Pass the preview_id and identical patterns'), but kb_id, root, and confirmed are left entirely to inference. With 4 of 6 parameters undocumented in both schema and description, compensation is only partial.

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 specific verbs and resource: 'save a local configuration and index the documents' for a knowledge base. It clearly establishes this as the commit/connect step following a preview, which distinguishes it from preview_knowledge_base, though it doesn't name that sibling explicitly.

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 precondition ('After the user confirms the previewed scope') and an exclusionary rule ('changed scope requires a fresh preview and confirmation'). This tells the agent when to call it and when to redirect to a new preview, though it doesn't name the sibling tool.

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 establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral policy beyond that: demo knowledge bases do not count as user setup, and the agent should stop asking if the user defers. It omits the rest of the status payload, but the added workflow guidance is substantive.

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 short sentences, front-loaded with the trigger and action, with each subsequent sentence carrying a distinct policy rule. No filler, though the phrasing is terse enough that 'setup' is only clarified by context.

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 should characterize the return value more fully; it surfaces only one field name (needs_knowledge_base) and leaves other possible status fields unspecified. For a simple read-only status tool this is adequate but not 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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless schema applies. The mention of 'needs_knowledge_base' is a return-state reference rather than a parameter, so it does not add 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 pairs a verb with a resource (check setup after installation) and hints at the returned state via 'needs_knowledge_base'. It does not explicitly distinguish itself from siblings like list_knowledge_bases or connect_knowledge_base, but the scope (post-install setup check) is discernible.

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 a clear trigger ('After installation') and a conditional follow-up branch (if needs_knowledge_base, ask the user for a directory in the current chat), plus a stop condition if the user defers. No alternative tools are named, so it stops short of full when/when-not routing.

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=false, so the safety profile is covered and the bar is lower. The description adds only that unindexed bases are excluded ('indexed'), with no detail on ordering or whether the result set is paginated or complete. Adequate but thin against the 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?

A single front-loaded sentence with zero filler; the action and its purpose are both stated in one pass. Nothing could be trimmed without losing meaning.

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 parameters and an output schema present, the return values need no explanation, and the description covers purpose and trigger condition. It is complete enough to call correctly, though slightly more on what the returned list contains would round it out.

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 of 4 applies. No parameter-related claims are made or 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?

States a specific verb (List) and resource (indexed knowledge bases), which clearly separates it from siblings like search_knowledge or preview_knowledge_base. The scope qualifier 'indexed' is useful, but the description does not explicitly contrast itself with the other listing/introspection tools (get_setup_status).

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?

'Before choosing a search scope' gives a clear usage context and implicitly sequences this call ahead of search_knowledge. It does not name alternatives or state exclusions, so it stops short of the explicit routing seen in 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 establish readOnlyHint=true and openWorldHint=false, so the description's added value is the clarification that it does not read document text and does not save configuration, plus the note that default patterns match Markdown. That is meaningful behavioural context beyond the annotations, though return-format specifics are absent.

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 short sentences, front-loaded with the core action and the side-effect constraints. No filler; only the slightly dangling "Defaults match Markdown" phrasing costs a point.

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 preview tool with annotations covering the safety profile and no output schema, the description is mostly sufficient, but with 0% schema coverage the unexplained kb_id parameter and include/exclude semantics leave a real gap an agent cannot close from structured fields alone.

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% across 4 parameters. The description compensates only partially: root is characterized as a user-supplied absolute directory and include/exclude defaults are described as Markdown-matching, but kb_id and the include/exclude syntax are never 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?

States a specific verb (Preview) and resource (user-supplied absolute directory) plus the scope boundary that no document text is read and no configuration is saved. It is clear what the tool does, though it does not explicitly name connect_knowledge_base, which is the sibling an agent would otherwise confuse it with.

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?

"Show the file count, patterns and sample paths to the user before connecting" gives an explicit temporal/usage condition that maps onto the connect_knowledge_base sibling. There is no stated when-not-to-use, but the pre-connection context is clear.

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=false, so safety is covered. The description adds genuinely new behavioral context: the returned content is the indexed snapshot and may differ from the current source file, and source_hash acts as a staleness guard. It still doesn't mention truncation or pagination behavior around max_chars/start_line.

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 short sentences with no filler; the core purpose is front-loaded and the staleness caveat follows immediately. Every sentence carries 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?

Read-only safety is covered by annotations and no output schema exists, so the description needn't document return shape. But with four parameters and 0% schema coverage, three parameters are undocumented anywhere, which is a real gap for an agent invoking the 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 carries the full burden, yet it only explains source_hash. The required doc_id and the max_chars/start_line windowing parameters are never described, leaving an agent to guess their meaning and 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?

States a specific verb and resource ('Read an indexed source snapshot') and clarifies it returns the indexed version rather than the live file. It does not name any sibling (e.g. search_knowledge) as the alternative, so sibling differentiation is left to inference.

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?

'Pass the search source_hash to reject stale citations' implies this tool is used downstream of a search that surfaced a source_hash, which is useful workflow context. However, there is no explicit statement of when to reach for this versus search_knowledge or list_knowledge_bases, and no exclusions.

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 only cover readOnly and openWorld, yet the description adds substantial behavior an agent needs: returned artifacts are unverified source versions and excerpts, retrieved text must be treated as data rather than instructions (a prompt-injection warning), metadata status/dates must be respected, and scores are ranking signals, not confidence. This is dense, non-obvious behavioral context that goes well 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?

Sentences are short, front-loaded, and each one carries a distinct piece of guidance (trigger, return type, safety rule, score interpretation, parameter disambiguation). No filler or repetition; the parameter clarifications are placed last where they belong.

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 correctly describes what comes back and how to interpret it, and it addresses the two least obvious parameters. The remaining gaps are the semantics of kb_ids/top_k and explicit routing versus sibling tools, which keeps it just short of 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 carries the full burden. It usefully disambiguates max_chars ('limits excerpt characters; it is not a token limit') and filters ('match metadata exactly'), which are genuinely clarifying. But query, top_k, and kb_ids receive no semantic treatment, so roughly three of five parameters remain undocumented.

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 frames the tool as finding evidence and returning 'source versions and excerpts,' which implies a knowledge-base search, so the action is inferable. However, it never names the resource explicitly ('search the knowledge base') and does not contrast itself with siblings like read_document or list_knowledge_bases, leaving the purpose somewhat implicit rather than stated with a clean verb+resource.

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 a clear triggering condition ('Find evidence before stating past facts') and a guidance rule ('No evidence means unknown, not false'), which is useful usage context. But it never states when NOT to use it or which sibling to prefer for full-document retrieval or enumeration, so routing guidance is only implied.

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