workflows_list_sample_workflows

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

This is a read-only list operation with no annotations to contradict, and the description communicates a non-destructive purpose clearly ('List...'). It goes beyond a simple verb to describe the specific return contents (names, locations, descriptions, and CLI commands), giving the agent expectation of what output to look for. It doesn't document edge cases like empty definitions or errors, but for a simple listing tool this is adequate.

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 reasonably sized and front-loaded with the core purpose in the first line, then details what's returned, then example prompts. The example prompts add some value for an agent selecting the right tool but could be seen as slightly redundant since the core description is clear. Still, no wasted sentences.

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?

There is an output schema present, so the description needn't explain the return format in detail. The tool is a simple parameterless listing operation with a clear purpose. It's reasonably complete given the low complexity, though it could mention that this is a read-only/inspection operation and whether it requires any special setup or environment context.

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 0 parameters and 100% schema coverage (empty schema), so there are no params needing explanation. The baseline for 0 params is 4, and the description appropriately focuses on what's returned rather than parameter handling, which is the right allocation for a parameterless tool.

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 clearly states what the tool does: 'List the available sample workflow and agent definitions' with specific details about what's returned (names, locations, descriptions of YAML files in a specific directory, and available CLI commands). This distinguishes it well from sibling tools like workflows_run_project_log_workflow, which executes workflows rather than listing them.

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 example prompts showing exactly when to use this tool ('What sample workflows are available?', 'List the declarative agent templates I can deploy to Foundry'). While it gives clear context for usage, it doesn't explicitly state when NOT to use it or name alternatives, though sibling tools like agents_list_agents are distinguishable from context.

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