foundry_get_folder

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

The readOnlyHint annotation already covers the safety profile, so the bar is lower. The description adds the behavioral detail that the result includes both the folder and its contents, which is useful. However, it fails to disclose what 'contents' encompasses (files, subfolders, documents?), how the result is structured (nested vs flat), or any permission-related behavior. The userId parameter hints at permission scoping but is not mentioned in the description.

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 a single, front-loaded sentence with no redundant or filler content. Every word is meaningful and efficiently communicates the core action and target resource.

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?

Despite the readOnlyHint annotation, the description is insufficient for an agent to fully utilize the tool. There is no output schema, and the description does not specify the return format, the exact composition of 'contents', behavior for multiple folders with the same name, or error conditions. The tool is not trivial enough to rely on the sparse description alone, and the lack of return structure guidance could lead to misinterpretation.

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 67% with userId and clientId already described. The description adds critical meaning to the primary parameter 'name' by specifying that it is a folder name, which the schema alone (a string with minLength 1) does not convey. This compensates for the uncovered 'name' parameter and makes the parameter semantics clear enough for invocation.

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 'Get a folder and its contents by name' uses a specific verb ('Get') and resource ('folder'), and explicitly indicates the return scope ('contents') and lookup method ('by name'). This clearly distinguishes it from sibling tools like foundry_get_structure, foundry_get_entity, and foundry_get_scenes, which target different resource types or broader scopes.

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 choose this tool over alternatives. It does not reference sibling tools such as foundry_get_structure (for full world structure) or foundry_get_entity (for individual entities), nor does it mention any exclusions or prerequisites. The only implied context is that a folder name is needed, but no usage scenario or alternative selection logic is given.

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