Organize Files

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the description is not responsible for stating that it modifies files. It adds extra context about the dry_run preview capability and the security-threat detection when content analysis is enabled. However, it doesn't describe what gets moved or altered (e.g., that files will be relocated within the directory), and it doesn't mention undo capability despite a sibling tool existing. With annotations covering the destructive nature, the description adds moderate value.

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 with no fluff, front-loaded with the main action. The second sentence provides two actionable tips. It is appropriately concise, though it could be structured to include a brief note about what the tool returns or how it differs from siblings without becoming verbose.

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?

With no output schema, the description should explain return values, but it doesn't. It also doesn't mention that changes can be undone (despite an undo sibling tool) or clarify the categorization logic. Given the tool performs a potentially destructive action and has many closely related siblings, this description is incomplete: an agent lacks critical information about side effects, reversibility, and selection criteria.

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 description coverage is 80%, so most parameters are already documented. The description adds meaningful context for use_content_analysis ('detect file type mismatches and potential security threats') and dry_run ('preview changes'), clarifying the purpose of booleans beyond the schema. It doesn't add anything for directory, response_format, or conflict_strategy, but the schema covers those adequately. This is above baseline because of the added parameter explanations.

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 the verb 'organize' and resource 'files' into 'categorized folders', which is clear enough. However, it does not differentiate from sibling tools like organize_by_content, organize_smart, or organize_by_type, which likely perform similar actions. The description lacks specifics on what 'categorized' means (by type? by content?) making it ambiguous among the many similar-sounding siblings.

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 guidance for two parameters (use_content_analysis and dry_run) but gives no explicit guidance on when to choose this tool over its siblings. It doesn't mention exclusions or alternatives, leaving the agent to infer which of the many organizer tools to invoke. The provided parameter guidance is useful but does not address tool selection.

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