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

The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral nuance: the three-view behavior, pagination handling, and the note about `chart_source_url` being a normalized grouping key rather than a pullable chart, plus the `resolved_chart` clarification and the advice to confirm via repo cloning. It does not contradict annotations and enriches the agent's understanding of 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?

The description is longer than average (~180 words) but well-structured with a lead sentence, a three-bullet section, and a note. Every sentence adds functional information; there is no filler. It is front-loaded with the main purpose and then details, which lets the agent quickly grasp the tool's core. It could be slightly tightened but remains efficient for the complexity involved.

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 8 parameters, 3 views, and pagination, the description covers all usage aspects: parameter-to-view mapping, defaults, pagination, and the subtlety of `chart_source_url` vs `source_url`s. It even provides a verification step via `repo_clone`. With an output schema present (though not shown here), the return value details are not required, and the description fills all necessary gaps for an agent to call it correctly.

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 100% schema description coverage, the baseline is 3. The description adds extra meaning for parameters: it clarifies that `top` and `examples` apply only to `summary`, `repo` and `value_paths` to `values`, and `limit`/`offset` to `deployments`/`values`. It also explains that `value_paths` paths from `summary` work as-is, including array forms like 'route.hostnames[]'. This goes beyond the schema's terse descriptions.

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 ('Get details for one chart') and the resource (by release id), and explains three distinct views (summary, deployments, values) that give it a precise scope. It references the sibling tool `kubesearch_search_releases` as the source of the id, which differentiates it from search. No ambiguity in what it does.

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 explicit guidance on when to use each view: 'Start here' for summary, 'use it to find a repo to drill into' for deployments, and 'prefer summary first' for values. It also tells the user to confirm via `repo_clone` when needed. However, it does not explicitly say when to avoid this tool in favor of others (e.g., when to use `kubesearch_grep_values` instead), so it misses a direct exclusion but still offers clear usage 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 establish read-only and idempotent behavior. The description adds meaningful context by specifying the scope ('every indexed HelmRelease/Application'), the substring-match nature, and the result shape (matched key path, snippet, source file). No contradictions with 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 concise sentences front-load the core operation, provide concrete examples, and mention the output format. Every sentence earns its place without unnecessary detail.

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 grep tool with full schema coverage, annotations, and an output schema, the description covers scope, semantics, use cases, and result content. Nothing essential is missing for an agent to invoke it correctly.

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%, so the schema fully documents query, limit, offset, and case_sensitive. The description adds useful examples and clarifies the query targets config keys/values, but does not materially expand parameter semantics beyond 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?

The description uses a specific verb ('grep') and resource ('Helm spec.values of every indexed HelmRelease/Application'), clearly distinguishing this from file-based repo grep tools. It also states the substring-match behavior and the return payload, leaving no ambiguity about what the tool does.

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 gives clear context for when to use it: finding real-world examples of config keys or values, with concrete examples. It does not explicitly name alternative tools or exclusion cases, but the Helm-values-specific scope makes the intended use obvious.

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 cover read-only/idempotent behavior, so the description adds value by disclosing the search semantics (substring, case-insensitive), the data source (public home-ops clusters), and the exact return contents (repositories, tags, deployment counts, sample repos). This goes beyond the annotations and enriches the agent's understanding.

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 focused sentences with no fluff. The first sentence front-loads the core action and scope, the second describes return values and equivalence. Every clause earns its place, making it easy to parse quickly.

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, the description doesn't need to detail return types. It covers the essential context: what the tool does, what data it searches, matching behavior, and result granularity. With annotations handling safety and schema handling parameters, the description is complete for this tool's complexity.

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 100% with clear parameter descriptions, so the baseline is 3. The description adds extra meaning by explaining the query parameter's matching semantics ('substring match, case-insensitive') and what the results represent (tag counts, deployment usage, sample repos), which complements the schema without redundancy.

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 uses a specific verb ('Search') and resource ('container image repositories'), and adds key semantics like substring match and case-insensitivity. It clearly distinguishes from sibling tools (search_releases, grep_values) by focusing on image repositories, and even references the equivalent kubesearch.dev /image 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 clearly states the context (searching image repos across public home-ops clusters) and the matching behavior. However, it lacks explicit 'when not to use' or alternative tool references, though sibling names make the distinction obvious. This is close to a 5 but missing an explicit exclusion.

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 and idempotentHint, so the bar for extra value is high. The description adds substantial behavioral detail beyond annotations: case-insensitive substring matching, grouping by chart source, ranking by public repo usage, normalized `chart_source_url` behavior, and the `resolved_chart` flag. This gives the agent accurate expectations about how results are structured and why grouping keys may differ from actual pullable sources.

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 first sentence is front-loaded with the core purpose, followed by result-grouping context and the id-to-detail linkage. The second paragraph is a dense but necessary note about normalization, and every sentence earns its place with no filler. The structure is well organized and appropriately sized for the tool's complexity.

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 is complete for an agent deciding whether to invoke this tool and how to interpret results. It covers search semantics, result grouping, ranking, how to follow up for full details, and the important normalization caveat. The output schema exists, so return-value details do not need to be restated, and annotations already cover safety and idempotency.

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%, so the baseline is 3. The description adds meaning beyond the schema by clarifying that `query` is a case-insensitive substring over chart names, giving concrete examples ('cert-manager', 'authentik'), and explaining that `chart_source_url` is a normalized grouping key rather than a literal registry URL. This supplements the schema's field descriptions usefully.

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 opens with a specific verb and resource: 'Search kubesearch.dev for Flux HelmReleases / Argo Applications by chart name.' It clearly differentiates from sibling tools by noting the returned `id` can be passed to `kubesearch_get_release` and by describing the homepage-search mirror, so an agent can distinguish it from `kubesearch_search_images` and other siblings.

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 gives clear context for when to use the tool: searching chart names/substrings across HelmReleases and Argo Applications. It also names the follow-up tool (`kubesearch_get_release`) for full details, but it does not explicitly state when NOT to use this versus the sibling image-search tool, so it falls just short of full exclusion 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by disclosing exactly what status information is returned (release tag, load time, cache directory, row counts), which goes 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?

Two sentences with no filler. The first sentence front-loads the action and output fields; the second provides a succinct use case. Every word 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 simple read-only status tool with no parameters and an output schema, the description fully covers purpose, output content, and usage context. It is entirely adequate given the tool's low complexity and sibling context.

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 zero parameters, the baseline for parameter semantics is 4. The description correctly avoids inventing parameter details, and the input schema confirms no parameters exist, so nothing is missing.

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 reports freshness and size of cached data, enumerating specific fields (release tag, load time, cache directory, row counts). This unambiguously distinguishes it from sibling search tools, which perform queries rather than status inspection.

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 notes the tool is 'useful to confirm how current the search data is', giving a clear use case. However, it doesn't explicitly mention when not to use it or name alternatives, though sibling tools imply those are for searching, not status checking.

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 idempotentHint=true and readOnlyHint=false. The description adds valuable lifecycle context: clones are temporary, have a TTL, and are auto-deleted. This goes beyond annotations to explain why the tool is optional, and does not contradict destructiveHint=false since the clone is temporary.

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, front-loaded with the action ('Delete a temporary clone'), and both sentences serve a purpose: the first states the action and rationale, the second clarifies optionality. No wasted words.

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-parameter tool with an output schema and strong annotations, the description covers the purpose, usage context, and lifecycle behavior (TTL, auto-deletion). It is fully sufficient for an agent to decide when and why to invoke it.

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 the parameter 'handle' described as 'The clone handle from repo_clone.' The tool description merely references this relationship without adding new meaning, so the schema carries the full semantic burden.

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 uses the verb 'Delete' with a specific resource ('temporary clone created by repo_clone') and clearly distinguishes this from sibling tools like repo_clone, which creates clones. The qualifier 'temporary' adds necessary scope.

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 states when to use it (to free disk before TTL) and when not to (since clones auto-delete after inactivity, making it optional). The alternative is effectively doing nothing, which the description implies by calling it 'polite'.

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?

The description discloses substantial behavioral details beyond the annotations: the clone is shallow, sandboxed, size/time-limited, auto-deleted after a TTL, resolves indexed names to real clone URLs and branches, and requires eventual cleanup. This is exactly the kind of context an agent needs for a stateful, non-read-only operation.

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 front-loaded with the core purpose, then adds precise operational details in compact sentences. Every sentence earns its place, covering input format, clone behavior, return value, companion functions, and cleanup without 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 is complete for a tool with one parameter, meaningful annotations, and an output schema. It explains what the caller receives, how the temporary resource is governed, and what follow-up actions are expected. Nothing essential for correct invocation is missing.

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 100% schema description coverage, the schema already documents the `repo` parameter, and the description adds meaningful extra context: it gives an example, explains that indexed names are resolved to the real clone URL and branch, and states which URL forms are accepted. This goes beyond the schema without being redundant.

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 uses a specific verb and resource: temporarily clone a public Git repository to review actual files. It clearly distinguishes itself from siblings by explaining that it returns a handle consumed by repo_list_files, repo_read_file, and repo_grep, and that repo_cleanup should be called afterward.

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 clearly conveys when to use the tool: when actual repository files need to be inspected, rather than relying only on metadata. It also names the companion tools and cleanup routine, but it does not explicitly state when not to use it or contrast it directly with the kubesearch_* alternatives.

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 signal readOnly, idempotent, and closed-world behavior. The description adds valuable behavioral details: search scope ('text contents'), optional glob filtering, return format ('file paths, line numbers, and matching lines'), and truncation handling. This goes beyond annotation basics and helps the agent predict tool output.

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, all informative. The first sentence captures the core action, the second adds an optional parameter, and the third provides practical usage advice. No filler or repetition; front-loaded and efficient.

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 search tool with output schema and rich annotations, the description covers key contextual aspects: prerequisite (cloned repository), optional filter, return format, and behavior on truncation. It doesn't mention case_sensitive or limit explicitly, but the schema fully documents those, and the truncation guidance substitutes for deeper pagination details.

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 each parameter including a description, so the baseline is 3. The description does not significantly expand on parameter meaning beyond what the schema provides—it only restates 'by handle' and 'glob' in narrative form. No new parameter-level insight 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?

The description states a specific verb ('Search') and a specific resource ('text contents of a previously cloned repository'), immediately distinguishing it from sibling tools like repo_list_files (list files) and repo_read_file (read one file). It also specifies the output (file paths, line numbers, matching lines), making the tool's purpose unambiguous.

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 the prerequisite of a prior repo_clone operation via 'previously cloned repository (by handle)', and offers explicit guidance for handling truncated results: 'narrow the search with a longer query or a glob rather than paging.' It does not explicitly mention when to use this over kubesearch_grep_values, but given sibling list and context, the usage is clear enough.

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 mark it read-only, open-world=false, and idempotent, and the description adds several behavioral details beyond those: the server keeps repos permanently cloned, results are grouped by repo and star-ranked, each group carries a handle for follow-up tools, and the pool object's syncing/ready/size indicates warming with non-final empty results. No contradiction with 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?

The description is dense but every sentence adds a distinct operational fact: scope, no-clone behavior, resource coverage, grouping/handle for follow-up, and pool-warming retry semantics. It is front-loaded with the core purpose and remains compact enough for the amount of context it provides.

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 search tool with 100% schema parameter coverage, an output schema, and clear annotations, the description covers the key selection and invocation concerns: what it searches, how results are grouped, how to follow up, and when an empty result is not final. No critical operational gap is apparent.

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%, so the baseline is 3 and the schema already documents query/glob/limit/max_per_repo/case_sensitive. The description reinforces that query is a substring and that grouping is by repo, but it does not add syntax or parameter-format details beyond 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?

The description opens with a specific action ('Substring-search') and resource ('actual files of the most popular indexed home-ops repositories'), and immediately distinguishes it from 'kubesearch_grep_values' by scope. It also notes no clone step is needed, making it clear this is a pre-warmed cross-repo search rather than a repo-local grep.

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 contrasts with kubesearch_grep_values ('not just Helm values like...') and tells the agent that returned handles are intended for repo_read_file/repo_list_files/repo_grep follow-ups. It also gives retry guidance while pool.syncing is true. This is clear contextual guidance, though it stops short of an explicit 'use X instead' exclusion statement.

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 and idempotentHint, covering the safety profile. The description adds useful behavioral context beyond annotations: the handle must come from repo_clone, and listing can be scoped via sub-path and glob. No contradictions.

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 core purpose, followed by optional parameters and a necessary prerequisite. Every phrase earns its place with no redundancy.

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 files tool with an output schema, the description covers the prerequisite (handle from repo_clone) and options (path, glob). It does not explicitly state whether the listing is recursive, but the glob pattern '**/*.yaml' implies recursive behavior, and the output schema likely clarifies return structure. No major gaps.

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 100%, with each parameter (handle, path, glob) fully described in the input schema. The description restates these options but adds no new semantic detail beyond examples already present in the schema, 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 a specific action and resource: 'List files in a previously cloned repository (by handle)'. This distinguishes it from sibling tools like repo_read_file and repo_grep, which operate on file contents. The optional path and glob filters are additional specificity.

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 gives a clear prerequisite via 'Use the handle returned by repo_clone' and explains optional scoping/filtering with path and glob. It does not explicitly name alternatives or when-not-to-use conditions, but the context is strong enough for an agent to understand when this tool applies.

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 read-only and idempotent hints. The description adds behavioral details about binary files being refused and large files being truncated, which goes beyond the structured 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?

Two sentences, front-loaded with the action, and each sentence earns its place without unnecessary elaboration.

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 a rich output schema and good annotations, the description covers the key prerequisites and constraints (prerequisite handle, binary refusal, truncation) sufficiently for an agent to use the tool correctly.

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 covers 100% of parameters with descriptions. The description reinforces the handle's origin but doesn't add significant new semantic information beyond what the schema already 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 clearly states the tool reads a text file from a cloned repository using a handle and relative path. It also mentions binary refusal and truncation, which distinguishes it from sibling tools like repo_list_files and repo_grep.

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 clear context: it works on previously cloned repos and instructs to use the handle from repo_clone. It doesn't explicitly name alternatives, but the usage context is unambiguous.

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