spss_add_files

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

With no annotations, the description carries the behavioral burden. It does disclose that the operation stacks cases, writes to an output_path, and requires IBM SPSS Statistics. However, it does not mention whether input files are modified, whether an existing output file is overwritten, or how conflicts between variable definitions are handled, which are meaningful behavioral gaps.

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 compact and front-loaded with the core action, followed by a concise parameter breakdown and the external prerequisite. Every clause adds information and there is no filler or redundant restatement of the tool name.

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?

The description covers the primary workflow and essential parameters, and an output schema is available for return-value understanding. However, it omits drop/keep semantics and lacks guidance on edge cases such as variable mismatches across files or how BY variables affect stacking, leaving an agent with noticeable uncertainty for non-trivial usage.

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 0%, so the description must explain all parameters. It meaningfully clarifies file_paths ('>=2 .sav files'), key_variables ('optional BY variables'), and output_path ('stacked result file'). However, drop and keep are completely undocumented in both schema and description, leaving their semantics ambiguous in a context where they could refer to cases or variables.

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 immediately states a specific action and resource: 'Stack cases from multiple files', with the clarifying synonym '(concatenate/union)' and the SPSS command 'ADD FILES'. This clearly differentiates the tool from nearby siblings like spss_match_files, which merges variables/columns rather than appending cases.

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 makes clear that this tool is for stacking/concatenating cases, implying it is the right choice when the goal is a row-wise union of .sav files. However, it does not explicitly state when not to use it, nor does it point to an alternative such as spss_match_files for variable-wise joining. Usage context is present but alternatives/exclusions are left implicit.

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