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

Annotations already mark the tool read-only and idempotent; the description adds useful behavioral guarantees: deterministic results, token-match explanations, and no external service or payment. This goes beyond the annotations and helps an agent predict side effects.

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 with no filler; the first sentence front-loads the action and inputs, the second adds behavioral guarantees. Every clause earns its place.

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?

With no output schema, the description only vaguely indicates results ('explain their token match') and does not describe result fields, limit behavior, or empty-result handling. For a search tool with nested constraints, this leaves some operational gaps, though annotations cover safety.

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 descriptions cover query and constraints, and the description reinforces 'natural-language need' and 'structured constraints'. However, the optional limit parameter has no schema description and is not mentioned in the description, so its semantics are left to inference from name/defaults.

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 'Search Faceabot's current prototype catalog', giving a specific verb, resource, and input mode (natural-language need plus structured constraints). It is clear about what the tool does, though it does not explicitly differentiate from siblings like match_offer_to_need.

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 the tool is for turning a functional need into catalog results, but it never states when to prefer find_skill over sibling tools such as match_offer_to_need or compare_capabilities. There is no when-not-to-use guidance or alternative routing.

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