svn_import

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

Without annotations, the description has the full burden of disclosing behavior. It mentions using a temporary file for the message, which is a minor behavioral hint. However, it does not state that the command modifies the repository, requires network access, or whether it is destructive. The return value or side effects are not described.

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 very concise, at only one sentence. While there is no wasted text, it lacks essential details, making it under-described. It is not verbose, but conciseness should not come at the cost of clarity.

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 has four parameters (three required without schema descriptions) and no output schema, the description is critically incomplete. It does not explain what the tool does, what the parameters represent, or what outcome to expect. This is a significant gap for an AI agent to use effectively.

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 schema has only 25% description coverage (only 'cwd' has a description). The description adds minimal value: it implies 'message' is used via a temp file, but it does not explain the meaning of 'src' or 'url'. For a required parameter that is undocumented in the schema, this is insufficient.

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 'Run svn import', which identifies the operation as the SVN import command. However, it does not explain what import does (e.g., importing a local directory into a repository). For users unfamiliar with SVN, the purpose is vague. Among siblings, it is distinguishable by name, but the description lacks a clear, self-contained purpose statement.

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 guidance on when to use svn_import versus alternative tools like svn_add or svn_commit. It does not mention prerequisites (e.g., source directory, remote URL) or typical usage scenarios. This leaves the AI agent without context for tool selection.

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