Record deterministic TypeScript evidence

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

Annotations alone indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false. The description adds meaningful behavioral context: it 'records evidence only; never declares the receipt verified or the code correct,' clarifies that it resolves an actually installed dependency, and describes how overloaded calls are handled. This goes beyond the annotations and does not contradict 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 two sentences, compact and front-loaded with the main purpose. It packs key behavioral details without fluff. Every clause earns its place, making it highly efficient for an agent to parse.

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 (8 params, no output schema) and the existence of a sibling, the description is reasonably complete on what the tool does but omits critical selection guidance. It does not mention when to use this instead of 'evidrift_record_json_pointer', nor does it specify the return value or failure modes (e.g., unresolved dependency). These gaps reduce completeness for an agent deciding between tools.

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 described. The description adds extra semantics, particularly for 'affectedCodeLine' (explaining its importance in overload resolution) and the requirement that 'packageName' be an actually installed dependency. This adds value beyond the schema definitions.

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 primary action: resolving an installed dependency and creating a content-addressed Evidrift receipt. It also gives a specific behavior detail about overloaded call-site signature selection. However, it does not explicitly differentiate from its sibling tool 'evidrift_record_json_pointer', so it lacks that distinction to reach a 5.

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 no explicit guidance on when to use this tool versus the sibling 'evidrift_record_json_pointer'. It implies use for recording evidence from a code path, but offers no conditions, exclusions, or alternative tool references. This leaves the agent to infer appropriate usage.

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