impacket_smbclient

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

With no annotations provided, the description takes on the full burden of behavioral disclosure. It explains authentication options (password vs. NTLM hashes), mentions that password is 'redacted in logs', and states target restrictions and permission requirements. It does not explicitly note that listing operations are safe/read-only, but the action choices (list_shares/list_files) make that implicit. This is solid but not exhaustive.

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 with the purpose in the first two sentences, followed by a clear Args list, Returns, and Note sections. Each sentence carries useful information—there is no filler. Despite listing 8 parameters, it remains scannable and well-formatted.

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 8 parameters, no annotations, and an output schema that exists, the description covers all essential aspects: purpose, parameter semantics, authentication methods, prerequisites, and what the tool returns ('SMB shares list or file listing'). It also warns about the required target allowlist and permission needs, providing sufficient context for an AI agent to invoke it 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?

The input schema has zero descriptions, so the description's Args section is essential. It fully explains all 8 parameters: target, domain, username, action, share, password, hashes, and timeout. For example, it clarifies the action enum values, the share name format (e.g., 'C$', 'ADMIN$'), and the hashes format 'LM:NT'. This exceeds the schema's information.

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: 'Browse and interact with SMB shares' and specifically 'Enumerates available shares and optionally lists files within a specific share.' This distinguishes it from siblings like impacket_psexec or impacket_secretsdump, which handle remote command execution or credential dumping, respectively.

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 conveys clear context for use: SMB share enumeration and file listing. It also provides prerequisites via the note: 'Target must be in tengu.toml [targets].allowed_hosts' and 'Requires valid credentials with appropriate share permissions.' However, it does not explicitly name alternatives or state when not to use it, so it falls short of a full 5.

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