recommend_libraries

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

With no annotations, the description carries the full disclosure burden, but it only describes a suggestion/analysis behavior. It does not disclose that the default apply_search_order=true can mutate session search order, that check_availability defaults to true and probes the environment, or that use_llm_refinement can invoke ctx.sample(). These are material behavioral traits for an agent deciding whether to call this tool.

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 compact and front-loaded with the core purpose, followed by scannable bullets. It is slightly repetitive because the opening sentence and the final sentence both express the recommending idea, but the structure helps an agent scan quickly.

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?

The output schema and high schema coverage remove the need to describe return values and parameter formats. However, for a 12-parameter, multi-mode tool with no annotations, the description omits important context such as session-mutating defaults and how the sampling/merge modes relate to the main recommendation workflow.

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 100%, so the baseline is 3. The description adds no parameter-level meaning beyond naming 'scenario' as the input; the schema's own parameter descriptions already carry the mode, k, samples, and flag semantics.

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 opens with a specific verb and object: 'Recommend libraries for a scenario or generate/merge sampling prompts.' It reinforces this with 'analyzes scenario text and suggests relevant libraries', and situates it among siblings by saying it runs after analyze_scenario and before execute_step and is used to discover which libraries provide needed functionality.

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 'WHEN TO USE THIS TOOL' section gives explicit triggers: immediately after analyze_scenario, on 'No keyword with name' errors, and when discovering needed libraries. It lacks explicit when-not-to-use guidance or named alternative tools such as check_library_availability or find_keywords, so it is clear but not a full routing map.

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