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

Annotations already declare readOnlyHint=true, covering the safety profile, so the description's burden is lower. It does add one genuinely useful trait beyond structured data — results are 'Ordered by upvotes' — but says nothing about pagination limits, result shape, or matching semantics beyond field scope.

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 short sentences, zero filler, with the retrieval semantics front-loaded and the ordering constraint trailing. Nothing needs trimming and nothing essential is buried.

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 no-output-schema search tool, the description discloses field scope and ordering but omits anything about the result set (fields returned, pagination bounds beyond schema defaults, whether hits are ranked by relevance or strictly by upvotes). Combined with the absence of usage guidance, it is adequate but thin.

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 100%, so a baseline of 3 applies, and the description actually earns above it: it defines what the 'query' parameter matches against (names, descriptions, tags), which the schema only labels as 'Search text'. It adds no equivalent meaning for page/pageSize, but those are self-documented.

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?

States a specific verb ('Full-text search') and resource (products) and narrows the searched fields to names, descriptions and tags, plus a result ordering. It is clear what the tool does, though it never names the sibling it contrasts with (list_products/get_product), so differentiation must be inferred.

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?

There is no explicit when-to-use or when-not-to-use guidance and no alternatives named, despite four obvious siblings (get_product, list_products, submit_product, upvote_product). An agent must infer that this is for text discovery rather than ID lookup or browsing, which is only weakly implied.

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