Search Godly design inspiration

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

Annotations already declare read-only and open-world, so the safety profile is free; the description adds real context beyond that: AND-matching of all query words across title/description/categories/domain, newest-first ordering when query is omitted, and a slug-only return shape. It doesn't state pagination behavior or result-count semantics, but those are minor given the limit/offset schema bounds.

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?

Four dense sentences, no filler, front-loaded with the resource and matching semantics before the follow-up routing hints. Every sentence carries an actionable fact.

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 correctly carries the return-shape burden by stating it returns slugs and where to take them. Combined with ordering and matching rules, an agent has everything needed to call it and act on the result.

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 40% (kind, limit, offset undocumented in schema), so the description must compensate. It does for `query` (all words matched against title, description, categories, domain) and `category` (points to list_categories), and the enumerated content types implicitly map to the `kind` enum; limit/offset remain self-explanatory from bounds and 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?

States a specific verb (search) plus the exact resource and its three content types (websites/landing pages, iOS apps, templates). It also distinguishes itself from siblings by naming get_inspiration as the detail follow-up and list_categories as the category resolver.

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?

Gives explicit when-to-use guidance and alternatives: omit `query` to browse newest first, pass a returned slug to get_inspiration for screenshots/details, and use list_categories for valid category names. An agent can route correctly without opening any other schema.

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