scan_contract

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

With no annotations, the description carries the full burden of behavioral disclosure. It honestly states limitations: 'Requires a verified ABI on Sourcify; returns matched=false with a reason when the ABI is unavailable or the fetch fails. Does not analyze bytecode, proxy implementations beyond the fetched ABI, or runtime behavior.' It also clarifies the interpretation of findings: 'Flags DANGEROUS CAPABILITIES... not proof of malicious intent.' The return shape is disclosed, providing a complete picture.

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 clear headers (PURPOSE, GUIDELINES, LIMITATIONS, EXAMPLE), making it easy to scan and front-loaded with the purpose. It is slightly longer than needed, but every section contains valuable information. The format is appropriate 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?

Given no output schema and no annotations, the description is remarkably complete. It explains the return structure, failure modes, limitations, and usage context in detail. It also provides an example, making it fully actionable for an agent. The description covers all necessary aspects for correct invocation and interpretation.

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 an example call with both parameters, which is helpful, but it does not add semantic meaning beyond the schema descriptions (address format, chain_id values). The example is a minor bonus but not a significant enhancement.

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: 'Assess a deployed EVM contract for structural danger primitives by ADDRESS — no descriptor needed.' It elaborates with specific actions ('Fetches the contract's verified ABI from Sourcify and flags every signable function that is a 'loaded gun'') and lists the specific primitives detected. It distinguishes from siblings by noting 'no descriptor needed' and explicitly stating it is not a signing gate, unlike preflight_transaction.

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: 'Call this to vet a contract an agent is about to interact with BEFORE any transaction is even built — the earliest possible safety check.' It also gives alternative tool guidance: 'Once a pending call is built, use preflight_transaction; neither this discovery scan nor check_descriptor is a signing gate.' This clearly explains when to use this tool versus alternatives.

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