GitHits

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

The description discloses response envelope shape, indexing behaviors (e.g., indexingEstimate, availableVersions/Refs, suggestedRefs), and error handling (INDEXING envelope, retry with longer wait_timeout_ms). This goes well beyond the sparse annotations (readOnlyHint=false, etc.) and adds meaningful context without contradicting them.

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 long but well-structured: it starts with purpose, then usage, then response/error details. While it repeats some indexing notions near the end, every sentence contributes useful information for a complex tool. A slightly tighter structure would earn a 5.

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?

There is no output schema, so the description correctly specifies the JSON envelope: {total, hasMore, files: [...], resolution, indexedVersion}. It also covers error cases and fallback strategies for indexing delays, making it complete for a tool with 16 parameters and no output schema.

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 high (75%), so baseline is 3. The description adds value beyond the schema by explaining usage patterns for key parameters: path_prefix for directory prefixes, extensions for language filtering, and wait_timeout_ms for retry decisions. It does not individually describe all params (e.g., limit, format), but the schema already covers those well.

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 clear verb+resource statement: 'List files in an indexed dependency.' It further distinguishes itself from siblings by positioning as the 'first choice for file/path enumeration' and explicitly contrasts with code_read and code_grep ('discover paths before code_read', 'scope code_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 gives explicit when-to-use guidance: 'First choice for file/path enumeration tasks', 'Use this to discover paths before code_read... and to scope code_grep.' It also describes addressing modes (target.registry+package_name vs repo_url+git_ref) and filtering options, plus retry behavior on INDEXING errors. This is comprehensive 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?

The description adds substantial behavioral detail beyond the annotations: deterministic matching, literal default vs. RE2 regex, ASCII case-insensitivity, indexing wait behavior, `targetResolution` provenance, and immediately queryable `availableVersions`/`availableRefs`. It does not contradict any annotation 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 dense and long, but each clause earns its place by covering distinct behavioral or usage aspects. It is front-loaded with the core purpose and differentiation, followed by operational detail. It could be slightly more scannable, but the length is justified by 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?

For a tool with 19 parameters, no output schema, and minimal annotations, the description covers a great deal: matching semantics, indexing fallback, error detail shape, and chaining to `code_read`. It does not explicitly address pagination via `cursor` or result limits like `max_matches`, leaving some completeness on the table.

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 only 42%, so the description carries heavy weight. It meaningfully explains the most complex parameters: `pattern` semantics (literal vs. regex, case sensitivity, byte limit), `target` forms, and `wait_timeout_ms` behavior. However, some parameters like `cursor`, `max_matches`, and context-line controls are not covered in the description, leaving minor gaps.

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 'Deterministic text or regex grep over indexed dependency and repository source files' — a specific verb, resource, and scope. It actively distinguishes itself from the sibling `search` tool by saying 'Use `search` for discovery instead,' so there is no ambiguity about its 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?

It gives explicit when-to-use guidance ('Use this when you know the pattern') and an explicit alternative ('Use `search` for discovery instead'). It also provides practical narrowing advice with `path`, `path_prefix`, `globs`, or `extensions`, and explains how to chain results into `code_read`.

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 the 150-line cap, silent truncation behavior, the `hint` field, binary file handling, target resolution provenance, indexing waits, and specific error types (`INDEXING`, `NOT_FOUND`). This goes well beyond the sparse annotations, which do not provide any of these behavioral details.

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 long but well-structured: it starts with purpose, then sibling relationship, then cap/truncation, response format, target scoping, and error handling. Every sentence carries useful information, though it could be tightened by removing a few schema-duplicated explanations.

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 complexity (6 params, no output schema, nuanced indexing behavior), the description is exceptionally complete. It explains the return shape, binary handling, truncation, target resolution, and concrete error-recovery steps, making the tool safe and effective to invoke without further documentation.

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?

While schema coverage is high (83%), the description adds critical context: 'Pass the same `path` emitted by `code_files`', mutual exclusivity of target scopes, and how to use `wait_timeout_ms` on `INDEXING` errors with `availableVersions`/`availableRefs`. It enriches the schema descriptions but doesn't fully restate every parameter.

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 exact file from an indexed dependency' and explicitly states 'it does not list directories', which clearly differentiates it from the sibling `code_files` tool. This is a specific verb+resource+scope statement.

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 explicit guidance on when to use this tool vs alternatives: 'Use `code_files` with `path_prefix` for file/path enumeration', 'Pick a focused window from a `search` / `code_grep` match', and 'On `NOT_FOUND` / `FILE_NOT_FOUND` call `code_files` to discover the actual path'. It also covers error-recovery usage.

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 key behavioral details: entries include a stable pageId, sourceKind (`crawled` or `repo`), source URL, and repo-specific fields. It implies a read-only operation via 'browse,' but does not explicitly state that no writes or side effects occur; annotations mark readOnlyHint=false, but there is no outright 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 is front-loaded and clear, but it repeats the instruction 'Pass a returned pageId to docs_read' twice (once in the search workflow, once at the end), which is redundant. It could be tightened without losing 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?

With no output schema, the description adequately explains return structure and usage flow. It relates to sibling tools (search, docs_read) and covers the key information needed to invoke the tool correctly. Pagination is left to the schema, which is acceptable.

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%, so parameters are already well-documented. The description adds context about output fields (pageId, sourceKind, etc.) but does not meaningfully enhance parameter understanding beyond the schema, which already covers `format`, `limit`, `after`, etc.

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 ('List') and a precise resource ('mixed package documentation pages'), clearly distinguishing this tool from siblings like docs_read and search. It explicitly positions itself as a browsing tool, avoiding ambiguity.

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 explicit guidance: use `search` for topic search, then pass the returned `pageId` to `docs_read`. It also states 'Use this to browse before reading a full page,' making the intended workflow unmistakable.

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 behavioral details beyond the annotations: it supports both hosted/crawled and repository-backed docs, includes totalLines in responses for pagination, and has repo-backed metadata for code_read. These are not present in the readOnlyHint/destructiveHint annotations and add useful context for the agent.

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 three sentences: purpose, usage guidance, and a bonus detail about repo-backed metadata. It is front-loaded and every sentence earns its place 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 annotations (read-only, non-destructive) and a fully descriptive schema, the description covers the essential behavioral aspects: purpose, pagination strategy, and repo-backed follow-up. It is complete enough even without an output schema, as it explains totalLines and metadata 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 schema already describes all parameters thoroughly (100% coverage), so the baseline is 3. The description adds value by explaining the start_line/end_line workflow and the role of totalLines in fetching slices, which goes beyond the schema's individual parameter 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 opens with 'Read a documentation page by page ID', which clearly states the tool's function with a specific verb and resource. It also distinguishes from siblings by noting support for both hosted/crawled and repository-backed docs, and mentions follow-up metadata for code_read, which helps differentiate it from code reading tools.

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 concrete usage guidance: how to read a page, when to use start_line/end_line for long pages, and that repo-backed results include metadata for code_read. It implies when to use the tool but doesn't explicitly state exclusions or name alternatives like docs_list for finding page IDs, though the schema does mention docs_list as a source for page_id.

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 all annotations false (readOnlyHint, openWorldHint, destructiveHint), the description carries the burden of behavioral disclosure. It explains that feedback 'feeds ranking and product quality' (an effect) and emphasizes accepted is always required. It does not discuss side effects like data persistence or non-reversibility in detail, but the core behavior is 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 well-structured with a front-loaded trigger ('Use after...'), clear mode markers, and no filler. Every sentence contributes to understanding the tool. It is appropriately sized for a 4-parameter tool.

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 feedback tool: it covers both usage modes, all parameter roles, and the downstream effect on ranking/quality. No output schema exists, but return values are not critical for this simple tool. It fully compensates for the lack of annotations.

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%, so baseline is 3. The description adds meaningful semantics beyond the schema by explaining the two modes: solution-tied vs. generic, and clarifying that feedback_text is strongly recommended in generic mode. This helps the agent decide how to populate parameters effectively.

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's purpose: 'Submit feedback on a tool result or the GitHits experience.' It uses a specific verb ('submit') and resource ('feedback'), and the 'Use after a GitHits result was helpful...' trigger contextualizes when it applies. It is easily distinguished from sibling navigation/search tools.

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 usage context: use after a GitHits result is helpful/unhelpful/etc. It explicitly explains two modes (solution-tied vs. generic) and when to choose each by passing or omitting solution_id. There are no alternative tools to reference, but it lacks an explicit 'when not to use' exclusion, which would push it to 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?

The description discloses key behavioral traits beyond annotations, including default output format (markdown), source repository provenance, trailing solution_id, the need to report citations to the user, the format: 'json' option, and how to pass solution_id to feedback. Since annotations are minimal (all false), this description fully carries the transparency burden.

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 well-structured with two paragraphs and front-loaded with usage guidance. However, it has minor redundancy: the instruction to use the unified `search` tool appears twice. Still, every sentence contributes meaningful 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 the tool's complexity, minimal annotations, and lack of output schema, the description is remarkably complete. It covers when to use, output behavior, provenance handling, and integration with `feedback`. It also handles edge cases like when package-scoped search is insufficient.

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 baseline is 3. The description adds extra value by explaining the default `format` behavior, the JSON output structure, language inference, and when to use `search_language` to force a language. This goes beyond simply restating 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 clearly states the tool's purpose: fetching canonical open-source examples, usage patterns, or API snippets. It uses a specific verb (needs, get) and resource, and explicitly distinguishes from sibling tools by saying to use `search`, `code_*`, or `docs_*` for known repositories.

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 explicit usage guidance: 'Use when...', 'Best for...', and when not to use (e.g., when package-scoped search was not enough, or for specific known repositories). It names alternative tools, making the decision process 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?

Beyond the readOnlyHint and destructiveHint annotations, the description discloses many behavioral traits: two modes (latest/range), default limit of 10, mutual exclusivity rules, error behavior (NOT_FOUND), response structure (source, mode, entries), output formatting options (body_lines, verbose, omit_bodies, format), and supported registries. This is rich behavioral context above what annotations provide.

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 long but every sentence serves a purpose, with a clear front-loaded 'Use when' directive followed by mode, addressing, output, and error details. It is well-structured and avoids redundancy, balancing density with completeness for a complex 11-parameter tool.

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 there is no output schema, the description fully explains return values and edge cases: source omission, NOT_FOUND, output previews, and formats. It also covers the full range of supported registries and the distinction between addressing modes. This makes the tool self-contained and complete for an agent.

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 baseline is 3. The description adds value by explaining how parameters interact (e.g., from_version triggers range mode, mutual exclusivity), the meaning of modes, and gives a concrete example. However, many individual parameter details are already in the schema, so the description augments rather than fully compensates; a 4 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 tool's purpose: 'Release notes for a package or GitHub repo, newest-first' and gives explicit usage triggers: 'when the user asks what changed in a package, wants release notes, or needs changelog evidence for a manual upgrade review.' This differentiates it from siblings like pkg_info or pkg_deps by focusing on changelog/release notes specifically.

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 explicit 'Use when' scenarios, including mentions of manual upgrade review, which helps an agent decide when to invoke it. However, it does not explicitly name sibling tools as alternatives or state when not to use this tool, so it falls short of the 'explicit when-not/alternatives' bar for 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?

Beyond the readOnlyHint, the description explains default runtime-only behavior, the transitive block with conflict detection and circular-dependency flags, and the performance trade-off of include_importers (quadrupling envelope size). This gives the agent useful operational context not conveyed by 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 yet efficient: it leads with use cases, explains default behavior, parameter interplay, and supported registries in about four sentences. No filler or 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 7-parameter tool with no output schema, the description covers return behavior (direct runtime deps, transitive block, importers), parameter effects, and performance implications, leaving little ambiguity about what the agent will receive.

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, but the description adds cross-parameter guidance: how lifecycle accepts concrete values or 'all,' that max_depth introduces conflict detection, and how include_importers layers provenance on top. This elevates the parameter semantics above the raw 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?

Description opens with explicit use cases ('what a package depends on, dependency groups, bounded transitive dependency footprint') and states the core action 'Analyze a package's dependency graph.' This clearly distinguishes it from sibling tools like pkg_info or pkg_vulns, which cover other aspects.

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?

Provides explicit when-to-use guidance in the opening sentence ('Use when...'), which covers the primary intents. It doesn't name alternative tools for exclusions, but the context is clear enough for deciding to use this 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 are readOnlyHint=true and destructiveHint=false; description does not contradict them. It goes beyond annotations by detailing default output fields (license, description, repo popularity, downloads, publish age, vulnerability status), verbose additions (GitHub language/topics/last-pushed, advisories, changes), and format=json behavior.

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?

Description is dense but well-organized: purpose, usage, default output, verbose option, format option, sibling pointer. Minor repetition of 'latest-version' but no fluff. Appropriate length 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?

No output schema, so description must explain return values; it does by enumerating default text fields, verbose additions, and json structured mode. It also directs to pkg_vulns for version-specific details, covering edge cases and making the description 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 coverage is 100% so baseline is 3. Description adds value with a concrete example ('npm' + 'express'), clarifies that verbose is 'Text only' and ignored for json, and explains that format=json gives a structured envelope. This exceeds schema 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?

Description opens with 'Use for a quick latest-version package adoption or health check', clearly specifying verb and resource. It distinguishes from sibling pkg_vulns by explicitly stating 'Use pkg_vulns for version-specific vulnerability details.'

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?

Description gives explicit usage context ('dependency triage') and clear when-to-use guidance. It names the alternative tool pkg_vulns for version-specific vulnerability details, and provides the required inputs (registry, package_name) with an example.

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?

Beyond the readOnlyHint and destructiveHint annotations, the description states 'The tool reports facts only and does not assign risk or decide whether to accept an upgrade' and discloses internal batch execution caps. These are meaningful behavioral traits not visible in structured metadata.

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?

Four sentences, each earning its place: usage trigger, evidence categories, fact-only limitation, and mode/semver guidance. Front-loaded with the most important selection information, 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?

For a complex tool with 10 parameters and no output schema, the description covers what to expect from results (facts only, evidence categories), how to invoke single vs batch, internal limitations, and exclusions. It is sufficiently complete for an agent to select and call the tool appropriately.

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%, so baseline is 3. The description mentions single vs batch mode and optional transitive evidence, but these are largely already in the schema (e.g., packages[] description says 'Mutually exclusive with single-package fields'). It does not add per-parameter meaning 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 opens with an explicit purpose: 'Use when the user asks whether to accept, assess, review, or investigate a dependency update from one version to another.' It names specific evidence categories (vulnerability checks, changelog range, deprecation metadata, peer dependency changes, transitive diffs), clearly distinguishing this tool from siblings like pkg_vulns or pkg_changelog.

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?

Provides explicit when-to-use guidance ('Use when the user asks whether to accept, assess, review, or investigate a dependency update') and a clear exclusion ('Use this instead of inferring acceptability from semver, including patch bumps'). This helps the agent select the tool over less precise reasoning paths.

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 declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, and the description adds rich behavioral context beyond that: it describes the return payload (count summary, per-advisory OSV ID, severity, affected ranges, fix versions), the separate malicious-package bucket, default text caps, and the effects of `verbose` and `format`. 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?

The description is a single dense paragraph, but every sentence earns its place: trigger, example, parameter explanations, and edge cases (unsupported registries, withdrawn advisories). It could benefit from bullet points or headings for scannability, but it remains efficient and front-loaded.

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 carries the full burden of explaining return values, and it does: count summary, advisory fields, malicious-package separation, and format/verbosity options. All 8 parameters are mentioned, along with limitations and example usage, making the tool fully understandable.

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 baseline is 3, but the description enhances every parameter with usage semantics: `version` for pinned vs latest, `min_severity` as a threshold with severity order, `advisory_scope` values and their effect, and `format` with default behavior. The example demonstrates correct invocation.

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 clear trigger: 'Use when the user asks whether a package or pinned version has known vulnerabilities, advisories, CVEs, malware, affected ranges, or fix versions.' This specifies the verb (check) and resource (package vulnerabilities) and explicitly distinguishes it from sibling tools like pkg_info or pkg_deps.

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?

Provides a 'Use when' statement plus a concrete JSON example, explains when to pass `version` (pinned) vs omit it (latest), and notes unsupported registries (vcpkg and Zig). It also explains how to use `min_severity`, `include_withdrawn`, and `advisory_scope`, giving unambiguous 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?

Annotations are uninformative (all false), so the description carries the full burden. It discloses several non-obvious behaviors: default completeness with searchRef when indexing is incomplete, AND semantics for structured parameters, ignored filters for source:'docs', and the effect of allow_partial_results. This goes well beyond the annotations and aids correct invocation.

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 dense paragraph, but it is front-loaded with the primary use case and then logically flows through requirements, edge cases, and follow-up actions. It is long due to the tool's complexity (16 params, multiple sources), and every sentence adds value, though bullet points would improve scannability.

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 high complexity (16 params, no output schema), the description covers the essential context: use case, target requirements, behavioral caveats, and hit-type-to-tool routing. It does not explicitly describe the overall response envelope or defaults like limit/format, but those are in the schema, so the description remains sufficiently complete for an agent to select and invoke 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 coverage is 63%, so the description must compensate, and it does. It clarifies the required query+target/targets combination, the mutual exclusivity of target and targets, the benefit of omitting source, and the interaction of structured parameters (AND semantics) along with the caveat for docs source. These insights are not fully evident from the schema 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 clearly states the tool's function: 'Search indexed dependency and repository code, docs, and explicit symbols' and frames the use case as 'discover relevant docs, source files, examples, tests, or APIs before reading exact files.' This distinguishes it from sibling tools like code_read and docs_read by focusing on discovery rather than reading specific files.

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 when to use the tool: 'Use when investigating a known package or repository... before reading exact files.' It then provides follow-up routing by hit type (documentation_page/repository_doc → docs_read; repository_code/repository_symbol → code_read) and mentions search_status for incomplete indexing, giving clear usage direction and 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 declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context: returns up to 5 matches, default output format, and the effect of passing format:json. This goes beyond the annotations without contradicting them.

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 concise—two sentences that front-load the key usage guidance and include the essential behavior and format options. Every sentence 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 lookup tool with two parameters, complete annotations, and a full schema, the description covers purpose, usage time, return limits, and output format. No output schema exists, but the description sufficiently explains what to expect. It is complete for an agent to select and invoke 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 a baseline of 3 applies. The description adds extra non-schema semantics, such as 'returns up to 5 matches' and clarifies the default and alternative output formats. It also reinforces that the query is a language name or partial name, which is already 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?

The description clearly states the tool's purpose: to find supported language names and aliases. It uses a specific verb ('finds') and resource ('language names and aliases'), and distinguishes itself from siblings by explicitly tying its use to `get_example` and language forcing.

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 explicit usage guidance: 'Use before get_example only when you need to force a language and are unsure of GitHits' exact language name.' This includes a clear when-to-use and a restrictive 'only' that implies exclusions. It also explains the output format options.

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 destructiveHint, covering safety. The description adds behavioral context: it is a follow-up polling/retrieval operation, it can return partial hits only when `allow_partial_results: true` was set, and it consumes a `searchRef`. It also highlights the camelCase/snake_case naming mismatch, which is useful. However, it does not describe error conditions or the response envelope, though format options are in the schema.

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 three sentences, front-loaded with the critical precondition ('Use only after...'), and every sentence earns its place. It covers when, why, and the key parameter mapping without 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?

For a tool with 2 well-documented parameters and no output schema, the description provides sufficient context: it explains the prerequisite (prior `search` returns `searchRef`), the three usage modes, and the parameter naming convention. It could mention response shape or termination behavior, but the format parameter already hints at it. Overall, it is complete enough for an agent to invoke 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 description coverage is 100%, so the baseline is 3. The description adds little beyond the schema: it reiterates that `search_ref` comes from a prior `search` response and passes through unchanged. The camelCase/snake_case note is already in the schema description, so the description does not significantly elevate parameter understanding. The `format` parameter is fully described in the schema with enums and default.

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's purpose: to check progress, fetch partial hits, and retrieve final results for a prior `search` that returned a `searchRef`. It uses specific verbs (check, fetch) and identifies the resource (search results), distinguishing it from the `search` sibling tool which initiates the 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 states when to use the tool: 'Use only after `search` returns a `searchRef`'. It enumerates three concrete scenarios (progress check, partial hits, final results) and implicitly excludes using it before a search or for new searches. This provides clear guidance against misuse.

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