omnisearch

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

With no annotations, the description carries the behavioral burden. It discloses that results span all types at once and that each result includes an entityType field, which is non-obvious and essential for interpreting a mixed-type result set. It also notes the homebrew-included-by-default trait. It does not explicitly state 'read-only', but 'Search' strongly implies it, and there are no side-effect concerns for a search tool.

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 three sentences with zero filler. The primary action is front-loaded, and each sentence contributes a distinct piece of information: scope, when to use, result format, and follow-up routing.

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?

Given there is no output schema, the description appropriately explains the key aspect of the return shape ('Each result includes an entityType field') and the default homebrew behavior. It could be slightly more explicit about result ordering or grouping, but nothing critical is missing for an agent to call the tool 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%, so the baseline is 3. The description adds no additional parameter meaning; it only restates the include_homebrew default ('Homebrew is included by default'), already visible in the schema. The query, ruleset, and per_type_limit semantics are all adequately covered by the schema's existing parameter descriptions.

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 a specific verb and resource: 'Search across ALL D&D 5e content types simultaneously' and enumerates example types. It clearly differentiates itself from the typed _search siblings by naming them ('spell_search, monster_search'), so an agent can immediately tell this is the cross-type entry point.

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?

It explicitly states when to use the tool: 'Start here when you don't know what type of content you need.' It also gives an exclusion/alternative: 'For deeper filtering within a single type, follow up with the typed _search tool.' This is explicit when/when-not guidance.

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