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

With no annotations, the description carries the burden and does disclose two real behaviors: matching is case-insensitive, and results are permission-scoped ("you see only what your role can read"). It also reveals non-obvious indexing of AI-generated photo/video descriptions and OCR text. It stops short of stating result ordering, pagination, or rate limits.

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?

Single sentence, front-loaded with verb and scope; the parenthetical field lists are dense but each list earns its place by telling the agent what is searchable where. Slightly long and could be broken with a semicolon-free clause, but no 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?

An output schema exists, so return shape needn't be described, and the searchable-surface list is thorough. Still missing: how results are ranked or truncated, what `limit` does by default, and whether shop_id must match the caller's own shop. For a cross-entity search tool those gaps matter.

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 0%, so the description must compensate; it does explain what an agent's query will match against, which is genuinely more useful than a bare string type. However it never mentions the `limit` parameter (1-50) or the q length bounds and default behavior, leaving one of three parameters undocumented in both schema and prose.

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 ("Search") and a precisely bounded resource ("one shop"), then enumerates every entity type and the field within it that matches (customer name/email/phone, property address, job summary, request title, note words, media descriptions/OCR/transcripts). This makes it clearly distinguishable from narrower siblings like customers_search, notes_search and media_search.

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 cross-entity enumeration implies "use this when you don't know which record type holds the answer," but it never says so explicitly and never names the narrower alternatives (customers_search, jobs_findByTag, notes_search, media_search) or when to prefer them. Usage must be inferred from the field list.

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