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

The annotations already establish that this is a read-only, idempotent, non-open-world operation. The description adds substantial behavioral context by explaining that the response includes crawl_log with every source fetched or checked, timing and results, last_verified_at, per-field sources, verification status, and what was verified versus not verified. It stops short of discussing pagination, error behavior, or caching, but it goes well beyond the annotations.

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 compact and front-loads the core purpose before listing detailed returned content. It is a dense single sentence, but each clause contributes useful information and there is no obvious filler.

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?

There is no output schema, so the description must carry the burden of explaining what the tool returns. It does this thoroughly by enumerating the published facts, crawl_log contents, last_verified_at, per-field sources, verification status, and the distinction between what was verified and what was not. For a single-parameter read-only retrieval tool, this is complete enough to call correctly.

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% and the single ref parameter is already documented with an example. The description still adds value by clarifying the composite format '<city>/<vertical>/<slug>' and by stating that the ref should come from search results, which tells the agent where to obtain 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 clearly states that this tool returns all published facts for one salon identified by a ref, and it names the key returned content such as crawl_log, last_verified_at, address, phone, hours, licence, registry, services, and booking link. It is specific about the action and resource, but it does not differentiate itself from the similar sibling tool get_salon.

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 implies usage by stating that the ref comes from search results, which gives useful context for when to call the tool. However, it does not explicitly say when to use this tool instead of get_salon, list_salons, search_merchants, or other sibling tools, nor does it describe exclusions.

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