recommend_workflow

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

Annotations already mark this read-only, idempotent and non-destructive, but the description adds real behavioral context: unknown goals return the whole directory rather than an error, status=ok means route selection not input readiness, required_information must be checked against confirmed data, and the tool explicitly does not calculate, understand arbitrary language, or manage dialogue. These are non-obvious traits an agent would otherwise get wrong.

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 core purpose and the skip condition are front-loaded, which is good, but the middle is a dense run of terse clauses ('status=ok selects a route, not input readiness') that read like internal shorthand. Several sentences (image-only routes, dialogue management) are useful but packed without structure, making it heavier than needed for a one-parameter tool.

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?

With no output schema, the description does supply return-shape cues (whole directory on unknown goals, status, required_information), which is what an agent needs to interpret results. What is missing is any description of the route record itself (fields, renderer vs calculation distinction beyond a passing mention).

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 carry the single 'goal' parameter, and it does provide useful guidance (a goal key like relationship_observation, or an unambiguous technique phrase, after interpreting language and negations). However, it never enumerates valid keys or the phrase format, so the agent still lacks a reliable way to construct a valid value.

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 calls this an 'optional keyword-based directory of supported calculation workflows', which hints at a goal-to-route lookup but never states plainly that it recommends/selects a workflow, so the name and description do not quite line up. It also does not explicitly differentiate itself from the many calculate_* siblings, leaving the agent to infer that this is a meta/routing tool rather than a calculation tool.

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?

Gives an explicit exclusion rule ('Skip when the requested tool is clear or the question is conceptual') and a procedure for multi-technique requests ('obtain each route separately') and for ambiguity ('ask only if ambiguity remains'). It stops short of naming concrete sibling tools to call instead, which keeps it from a 5.

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