find_workflow

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

Annotations already cover readOnly/idempotent/openWorld safety, and the description adds real context beyond them: output is a few RANKED summaries (not full graphs), sourced from saved JSON including hand-built ones, with a named load path. It doesn't mention ranking criteria or result-count behavior beyond the limit param, keeping it short of a 5.

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?

Front-loaded with the core value proposition and efficient throughout, though the parenthetical list of summary fields and the double aside ('hand-built ones included') make it slightly denser than needed.

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?

Output schema exists, so return-value detail is optional, yet the description still characterizes the response (family, base model, resolution, tags, match reason) and the load path. The only gap is the undocumented limit parameter.

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 coverage is 0%, so the description must compensate. It does well for 'intent' by explaining natural-language phrasing and giving a concrete example, but 'limit' is never mentioned in the description and has no schema description, leaving one of two parameters fully undocumented.

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?

States a specific verb (find) and resource (saved workflows) plus the goal-oriented input style, and explicitly distinguishes itself from list_workflows and import_workflow. An agent can tell what it returns (ranked summaries) without opening the schema.

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?

Explicit when-to-use ('reuse beats rebuilding', prefer this over importing each result of list_workflows) and names the follow-up alternative (import_workflow(name=...)) plus the rule that this never returns full graphs. Routing is unambiguous.

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