RepoPilot

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

Annotations already declare read-only/idempotent, and the description adds behavioral detail: it returns a concise brief with watchouts, evidence confidence, and explicitly does not dump the full generated artifact. This adds context beyond the safety hints, though not extensive.

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-loads the usage scenario, and efficiently packs the return contents, alternative tool, and parameter constraint without waste.

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 an output schema present, the description need not enumerate return fields. It covers when to use, what to expect, and an explicit alternative, making it complete for a decision-brief 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 100% with detailed descriptions for repo and package. The description's 'Pass exactly one of repo or package' reinforces the oneOf constraint but adds no new meaning beyond the schema, meriting the baseline score.

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 explicitly states the action ('CALL when...') and the resource (unfamiliar repository) with specific use cases (depend, fork, learn, deploy). It distinguishes from siblings by naming get_artifact as the alternative for file-level orientation.

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 clear trigger conditions ('when entering an unfamiliar repository or deciding whether to depend on, fork, learn from, or deploy it') and explicitly recommends get_artifact for file-level needs. Also gives the 'exactly one of repo or package' parameter constraint.

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 valuable behavioral context: output is deterministic, it never approves a merge (limit on its authority), and it notes repo caching for hotspot context. It does not detail receipts format, but with readOnlyHint covering the safety dimension, 4 is generous but warranted.

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, front-loaded with when to call, the core value (deterministic score with receipts), input modes, and a critical behavioral caveat. Every clause carries information; zero 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?

Output schema exists so return format needn't be detailed. The description covers invocation timing, input-mode disjunction, scoring dimensions, determinism, and non-approval semantics. It doesn't detail the receipt structure or caching behavior, but given the good annotations and output schema, this is adequately 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 63%, and the description fills key gaps: it explains the input-mode semantics (repo+PR OR diff), states repo may accompany diff for cached hotspot context, and notes files array is 'privacy-preserving... contains no source' — clarifying that line counts may be placeholders. This adds meaning beyond the oneOf constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it computes a 'deterministic 0-10 change-shape score' with receipts for specific factors (size, spread, missing tests, sensitive paths, hotspots, blast radius). The verb 'check' plus resources (PR/diff) and the distinct scoring behavior distinguish it from siblings like check_dependency or analyze_repo.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'CALL before merging a pull request or after producing a local diff', giving concrete timing. It lists valid input combinations ('repo+pr OR diff; repo may accompany diff') and clarifies it 'prioritizes review and never approves a merge', which sets expectations for when it's appropriate vs not.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds a valuable caveat that a 'favourable result does not validate an exact package version or compatibility,' and clarifies the output is a repository-level recommendation, 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?

The description is three sentences, each earning its place: trigger, output contents, exclusion, parameter rule, and caveat. It is front-loaded with the trigger and contains no unnecessary 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?

With a rich output schema and annotations, the description fills the remaining gaps: when to invoke, a clear exclusion, and a critical limitation about version validation. It is complete enough for an agent to decide to use the tool and understand its scope.

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 already documents both parameters with descriptions and a oneOf constraint. The description reinforces this with 'Pass exactly one of repo or package,' which adds prose clarity but no new information. Given 100% schema coverage, the baseline of 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 states a specific trigger ('about to add, upgrade, trust, fork, or deploy') and a specific resource ('npm package or public GitHub repository'), followed by a detailed list of returned fields. It also explicitly says 'DO NOT use for code navigation,' which differentiates it from sibling tools like analyze_repo.

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 clearly states when to use ('CALL when...') and when not to use ('DO NOT use for code navigation'). It does not name alternative tools, but the explicit trigger and exclusion provide strong guidance for selection among siblings.

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 readOnly, openWorld, idempotent, non-destructive. The description adds valuable behavioral detail beyond these: it discloses that on a cache miss it uses bounded live GitHub/OpenSSF evidence with limited confidence and explicit unknowns rather than fabricated certainty. This is honest about limitations and return variability based on cache state.

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, tightly packed with useful information: when to call, what's returned, accepted formats, and behavioral caveats. No wasted words or repetition of annotation content. Front-loaded with the trigger condition.

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?

Tool has an output schema and rich annotations, so description needn't cover return value structure. It covers trigger condition, target format inputs, evidence sourcing behavior, and confidence caveats. For a comparison tool with simple two-string inputs and disclosed fallback strategy, this is 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 both parameters a and b are documented. The description also adds meaning by explaining accepted formats (owner/repo, GitHub URL, npm package name, npm:@scope/pkg) which extends beyond the schema's generic 'repo or npm package target'. However, it doesn't clarify dimensional/ordering semantics (e.g., whether a/b order matters) beyond what the schema provides, so a 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 the tool compares two repository/dependency choices and lists what it returns (preferred candidate per use case, trade-offs, confidence, evidence gaps). It explicitly scopes to 'exactly two' choices, distinguishing it from single-repo analysis siblings. The accepted target formats are enumerated.

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 CALL ('when the user is choosing between exactly two dependencies or repositories') and implies when NOT to (single choice). It describes the fallback behavior: cached analyses preferred, bounded live evidence on miss with explicit unknowns rather than guessing. This provides strong guidance for selection.

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 detailed behavioral context beyond annotations: resolution of tags/ranges to highest match, adoption of alias keys, behavior without project snapshot (compatibility reported as unknown, project_snapshot_supplied: false), application of named policy profiles, and the explicit statement that the tool never installs or edits. All align with the readOnlyHint, idempotentHint, and destructiveHint 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?

Every sentence adds distinct value. The first sentence is a direct action command. The structure flows logically from when to call, input behavior (target format, alias handling), optional parameters, policy, what it checks, and a closing safety statement. 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 moderate complexity (4 params, nested objects) and the presence of an output schema (not shown), the description covers all aspects: invocation timing, input semantics, optional parameters, policy, and return highlights (blockers + verification plan). It is sufficient for an agent to use 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 only 25%, requiring the description to compensate. The description explains that 'change' accepts alias keys (adopted and reported), 'to_version' can be version/tag/range with server-side resolution, 'from_version' can be inferred from project snapshot, and optional 'project' triggers additional compatibility checks. This significantly enriches understanding 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 states a specific verb+resource: 'CALL immediately before adding or upgrading an npm dependency' and explicitly limits scope to npm packages. It distinguishes itself from siblings like 'check_dependency' by emphasizing project context and evaluation rather than simple lookup.

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: 'CALL immediately before adding or upgrading an npm dependency.' It also explains when to include a project snapshot (supply for compatibility/verification plan, omit for registry-only) giving actionable guidance. However, it does not explicitly mention when not to use this tool or directly compare with siblings like 'check_dependency' or 'verify_dependency_change'.

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds valuable context beyond annotations by noting that the artifact is 'cached' and that the agent should verify-before-trusting, implying potential staleness. It also reinforces idempotency with the explicit 'Do not call again' guidance.

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 most important usage timing ('CALL before substantial code work'), and each sentence adds distinct information: when to use, what it returns, and a critical constraint. 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?

The tool is well-specified: it has an output schema for return values, 100% parameter coverage in the schema, and strong annotations. The description covers the situational context, behavior, and constraints. The missing details about return format are handled by the output schema, making the overall definition 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 100% for all three parameters (repo, format, package), so the schema already provides full semantic detail. The description adds only 'Pass exactly one of repo or package,' which is already encoded in the oneOf constraint. No additional parameter insight is provided.

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 orient an agent in an unfamiliar repository by returning cached CLAUDE.md-style artifacts or Cursor rules. It uses a specific verb ('CALL') and resource, and scopes the use case to needing key files, entry points, architecture hypotheses, and reading order, which distinguishes it from sibling analysis 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 explicit trigger conditions ('before substantial code work in an unfamiliar repository') and a clear when-not-to-call condition ('Do not call again if the artifact is already in context'). However, it does not explicitly name alternative sibling tools or state when to prefer them over 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 already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful context beyond annotations: it discloses that task text is used only for bounded local matching and never persisted raw (a privacy/data-handling detail annotations don't capture), and that the verification contract is 'short-lived.' It also discloses that the tool grounds analysis against a 'checked SHA,' which is behavioral context about how results are derived. This is solid supplementary disclosure.

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 compact—about three sentences—and front-loads the critical usage directive ('CALL before editing') in the first three words. The output enumeration is efficient. The only slight redundancy is that 'against repository evidence and a checked SHA' in the title somewhat overlaps with the description's 'analyzed-vs-checked SHA relation.' Otherwise 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?

This is a 7-parameter tool with a nested intent object, but an output schema exists (which relieves the description from explaining return values). The description's coverage is strong on what the tool returns and when to call it. The 43% schema coverage gap is partially mitigated by the description's mention of bounded matching and SHA analysis. Given the tool's complexity, the description is solidly adequate—not exhaustive, but it conveys purpose, workflow, privacy, and output scope without redundant detail.

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 only 43%, with several parameters lacking documentation: task, intent, max_files, and checked_sha have no schema descriptions beyond types. The description compensates partially by implying checked_sha is the 'checked SHA' against which analysis relates, and mentions max_files implicitly via 'bounded reading order.' However, it doesn't explicitly explain the task/intent relationship or the checked_sha validation semantics. The description adds meaning for checked_sha (the core analytical anchor) but leaves task/intent semantics to be inferred from the surrounding prose.

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 imperative ('CALL before editing an unfamiliar public repository') and clearly enumerates the distinct outputs: reading order, relevant files, dependency consumers, test obligations, SHA relation, evidence provenance, and a short-lived verification contract. This distinguishes it from siblings like check_dependency and verify_dependency_change. The line 'Task text is used only for bounded local matching and is never persisted raw' adds a privacy boundary that further clarifies 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?

The description explicitly states when to use it ('before editing an unfamiliar public repository'), which is a precise trigger condition. It implies this is a pre-edit planning step distinct from the sibling tools that check/verify changes after the fact. The 'CALL before editing' phrasing serves as an explicit when-not context, and the existence of sibling verification tools establishes the workflow ordering. While it doesn't name specific alternatives, the workflow positionality ('before editing') is strong 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, idempotentHint, and non-destructive behavior. The description adds valuable behavioral detail: it never runs commands, never stores diff/check output, and labels receipts as 'caller asserted'. This contextualizes what the tool does with inputs and outputs, going beyond the annotation basics. 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 three sentences that are information-dense and front-loaded with the critical usage cue. Every sentence earns its place: when to call, what it does, and what it never does. There is no redundancy, and the structure supports quick comprehension.

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 high complexity (4 parameters, deeply nested schemas, output schema present), the description provides a useful high-level overview but omits details about the optional diff parameter, how to construct the evaluation/after/checks objects, and how the 'exact evaluated target' maps to fields. The output schema exists, so return values don't need explanation, but input semantics are only partially covered. Adequate with clear 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 0%, placing the burden on the tool description. The description gives high-level mappings ('evaluated target' to evaluation, 'resolved result' to after, 'caller-reported proof receipts' to checks) but does not explain parameter roles, required fields, or relationships in detail. Given the large, nested schema, this is insufficient to help an agent correctly construct inputs for this complex tool.

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: it compares an evaluated target with a resolved result and caller-reported proof receipts, reports missing/failed evidence and residual risk, and labels receipts as caller asserted. This goes beyond a mere verb+resource and distinctly describes the verification workflow, setting it apart from sibling tools like evaluate_dependency_change.

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 opening sentence 'CALL after changing the manifest/lockfile and running local checks' gives an explicit when-to-use instruction. It also clarifies a key exclusion: 'It never runs commands or stores diff/check output', which helps agents decide when not to use it. However, it does not name alternative tools or explicitly contrast with evaluate_dependency_change, so it lacks a full when-not-to-use comparison.

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