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

Annotations already carry the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the remaining burden is low. The description adds genuinely non-obvious behavior: suggestions are derived from transformer chains in real example workspaces, and the response contains suggested transformers, typical chains, and example workspaces – important since no output schema exists. It does not explain ranking or how many candidates feed the result.

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?

Two sentences, front-loaded with the action and immediately followed by the input shape and return contents. The two examples are long but each earns its place by demonstrating a distinct task style. Slight redundancy between 'based on transformer chains in real example workspaces' and 'typical chains and example workspaces' in the return list.

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?

For a read-only, two-parameter recommendation tool with no output schema, the description covers what it does, what the input should look like, where the knowledge comes from, and what comes back. What is missing is the follow-up path (e.g. pointing to get_transformer_details or search_fme_transformers once a suggestion is returned), which would make the tool chain self-navigating.

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 only 50%: the 'limit' parameter is documented in the schema but 'task' has no description there. The description compensates by specifying that the task should be plain language and supplying two worked examples of the expected phrasing, which is real guidance beyond minLength/maxLength constraints. It does not mention that overly broad tasks may yield weaker suggestions, a minor remaining gap.

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+resource ('Suggest FME transformers') and pins the input modality ('task described in plain language'), which separates it from keyword-oriented siblings like search_fme_transformers. It also states the basis of the suggestions ('transformer chains in real example workspaces'). It stops short of naming a sibling and contrasting with it explicitly.

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?

Usage is implied well through two concrete natural-language examples ('find features within 100 m of a road and write a report', 'read a CSV, geocode addresses and load to a database'), which teach the agent what kind of input to send. However, there is no explicit when-to-use/when-not guidance and no routing to alternatives such as search_fme_transformers for keyword lookup or get_transformer_details for deep dives.

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