Search characters, locations, plots, notes and items

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

Annotations declare readOnlyHint=true, and the description's words 'lookup' and 'search' are consistent with a read-only operation. However, the description does not disclose additional behavioral traits such as default pagination (limit=50), whether includeSecrets defaults to false, or how active filtering works. The annotation lowers the burden, but the description still adds limited behavioral context.

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 concise—two sentences—and front-loads the core idea ('Targeted lookup') with illustrative examples. It avoids filler, although for a tool with 8 parameters, a bit more structured parameter context would improve clarity without harming conciseness.

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 8 parameters, only 13% schema coverage, no output schema, and minimal annotations, the description leaves major gaps: return format, pagination limits, the role of query vs. name, how active and includeSecrets affect results, and what 'where a character is' means in terms of parameters. The examples are helpful but not enough for reliable invocation.

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 only 13% (only worldId has a description). The description's examples hint at worldId, kind, and locationId, but it does not explain the semantics of query, name, limit, active, or includeSecrets. Since the schema is mostly silent and the description does not compensate, agents will struggle to set parameters correctly.

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 states a specific verb ('search', 'lookup') and resource ('characters, locations, plots, notes and items'), and the example questions clarify the intended function. It is clearly distinct from sibling tools like list_worlds and get_world_overview, which are not targeted searches.

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 usage through examples ('all characters in a world', 'where a character is'), but it never explicitly contrasts with sibling read tools like get_current_context or get_world_overview. There is no 'when not to use' guidance, so the agent must infer the appropriate scenario.

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