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

With no annotations provided, the description carries the full behavioral burden, and it does substantial work: it discloses the percentile method, that all 26 cantons are scored, that each evidence figure carries value/unit/rank/source/year, and that scores reflect order under the stated weights, not universal suitability. It does not discuss response shape or side effects, but for a recommendation tool these are reasonably covered.

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 dense but every sentence earns its place: it front-loads the tool's purpose, then gives the category definitions, the scoring method, and the crucial caveat that results are relative under stated weights. There is no fluff or repetition of schema fields.

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 an 8-parameter tool with no annotations and no output schema, the description provides enough context to understand the weighted-scoring semantics, the parameter meaning, and the kind of evidence returned. It does not explain default behavior when weights are omitted or exactly how infra fits alongside the five named categories, but the schema partially covers those aspects.

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%, so the description compensates by decoding five category parameters into concrete submetrics such as cost = rent/premiums/electricity and env = sunshine/crime/vacancy, while confirming the 0–3 weight range. It does not add meaning for infra or international_community beyond the schema, but those parameters already have descriptions.

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 names a specific verb and resource: 'Personal canton recommendation' for deciding where to live in Switzerland, and it clearly distinguishes the tool from generic ranking by describing weighted 0–3 category inputs and the transparent percentile method. This also differentiates it from siblings like compare_cantons and rank_by_metric, which would not be personal or weighted.

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 use case is implied through 'Where should I live in Switzerland?' and the weighting model, so an agent can infer when personal preferences matter. However, it never explicitly states when to prefer this over compare_cantons or rank_by_metric, and gives no exclusion criteria or prerequisites.

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