agent_template_recommend

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

With no annotations provided, the description carries the full behavioral burden. It discloses that recommendations are 'live template match against the installed template dirs' ranked by relevance, and explicitly states the team_composition layer is 'static seed, not a live probe' — this distinction between live and static behavior is genuinely valuable and goes beyond what structured data reveals.

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 well-structured with two labeled layers, making the dual-purpose output easy to parse. The sentence explaining the static nature of team_composition is valuable but slightly verbose. Overall concise and front-loaded with the core purpose, though the layer breakdown could be tightened.

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 tool has an output schema, so return values need not be described. With 2 optional params at 100% schema coverage, the description effectively complements the schema by clarifying the output structure (two layers) and the behavioral distinction between them. Coverage is good for a moderately complex dual-output tool.

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 both parameters (keywords, task_type) already have clear descriptions with examples in the schema. The main description adds the project-type list for task_type (web-app/api-service/data-pipeline/library/refactor/bugfix), which enriches the semantic understanding. However, it doesn't describe how keywords interact with task_type or whether both can be provided together.

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 a specific verb ('Recommend') plus resource ('Agent templates') and adds a distinct secondary purpose (team shape for known project types). It effectively differentiates from siblings like agent_template_list (listing templates) and agent_reuse_recommend (reuse recommendations), establishing its unique job of recommending templates and team composition.

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 explains when the team_composition layer applies ('when task_type names a project type') and explicitly names which project types qualify. It also clarifies that team_composition is 'a static seed, not a live probe', which tells the agent about limitations. It doesn't explicitly name alternatives or exclusions, but the two-layer breakdown gives clear context for when to use versus other recommender tools.

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