list_compositions

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic operation without mentioning return format, pagination, sorting, or side effects. For a read operation, it would be valuable to note that it is non-destructive and what data is returned (e.g., composition names/IDs). The minimal disclosure leaves the agent uninformed about output structure or constraints.

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, well-structured sentence with zero wasted words. It conveys the core function efficiently and is easy to parse. Every word earns its place.

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 that there is no output schema and no annotations, the description is complete enough for a simple list operation. However, it omits useful details such as whether the result is an array, what fields are returned (e.g., composition ID, name), and any ordering. For a tool with many siblings, a slightly richer description would improve contextual understanding.

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 tool has zero parameters and schema description coverage is 100% (trivially). With no parameters to document, the description adds no specific semantic value beyond what the schema provides. However, the baseline for zero-param tools is 4, as the description is clear about the operation. It does not need to explain parameters that don't exist.

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 'List all compositions in the project' uses a specific verb ('list') and resource ('compositions'), clearly distinguishing it from siblings like create_composition, delete_composition, and get_composition_info. The scope is explicit (all in the project), leaving no ambiguity about the tool's function.

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?

No explicit guidance on when to use this tool versus alternatives such as get_composition_info or duplicate_composition. The description implies basic listing functionality but does not clarify when a user would prefer this over other list tools (none exist) or how it relates to other composition operations. Usage is implied but not formally stated.

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