resolve_source

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

Annotations already declare the tool as read-only, idempotent, and non-destructive, which covers the main behavioral safety profile. The description adds minor context with 'verified' and 'allowed', implying that the offset must be pre-validated and the file must be whitelisted, but it does not detail error behavior, permissions requirements, or side effects. Since annotations are strong and the description adds some useful nuance, a score of 3 is appropriate.

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, front-loaded sentence that efficiently states the core action. It is appropriately brief and avoids fluff, but its brevity is at the expense of completeness. For a concise description, it does its job, though it could be slightly expanded without losing efficiency.

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 that the tool has no schema descriptions and appears to be part of a larger profiling workflow, a one-sentence description is insufficient. It does not explain the role of the tool relative to siblings like 'get_source_context', the prerequisites for using it, or what the output represents. While an output schema exists, the description itself leaves too much undefined for an agent to confidently invoke 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?

With 0% schema description coverage, the description must compensate for the lack of parameter documentation. It loosely references 'module offset' and 'ELF/debug file', which map to module_offset and binary_path, but it omits any explanation of runtime_address, which is an optional but potentially important parameter. It also does not clarify the meaning of 'verified' or 'allowed' in relation to the inputs, leaving significant semantic 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 states a specific action ('resolve') and a resource ('verified module offset'), but the meaning of 'resolve' is ambiguous—it could mean mapping an offset to a source line, a symbol, or something else. It does not clearly differentiate from sibling tools like 'get_source_context', which likely overlaps in functionality. The phrase 'allowed ELF/debug file' adds context but not enough to fully clarify the tool's purpose.

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 offers no explicit guidance on when to use this tool versus alternatives like 'get_source_context' or 'analyze_profile'. It does not mention prerequisites, such as verifying the offset or obtaining an allowed file list, nor does it state exclusions or typical use cases. The only implicit guidance is the focus on 'verified' and 'allowed' inputs, which is insufficient.

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