Get character

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

Annotations already declare the read-only and idempotent safety profile, and the description adds substantial behavioral context beyond annotations: the response shape varies by game-system adapter. It discloses that item descriptions are omitted, that adapter-less actors expose only name/type/image, and that similar names are suggested rather than guessed, preventing hallucinated lookups. This is meaningful behavioral disclosure beyond readOnlyHint/idempotentHint.

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 front-loaded with the core purpose — 'Overview of one actor with few tokens' — and every subsequent sentence contributes information about output contents, adapter fallback, identifier semantics, or the sibling tool for full entity data. It is dense but not bloated, and avoids repeating schema text or annotation hints.

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 present, the description carries the burden of explaining the return contents, and it does so thoroughly: head values, adapter-specific value block, item fields, effects/actions, spellcasting, and the minimal fallback case. It also covers identifier lookup behavior and routes to get-character-entity for deeper item data, giving an agent everything needed to call the tool correctly for a single-parameter read-only operation.

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?

The schema already documents the identifier parameter at 100% coverage, including 'Id of the actor, its exact name (case does not matter) or the id of one of its tokens'. The description adds useful semantic behavior beyond the schema, namely that similar names are suggested and never guessed. It does not need to repeat the schema text, but the added matching behavior pushes it above baseline.

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 the tool returns an 'Overview of one actor' and enumerates the included data: head values, adapter-dependent value block, items with id/name/type, effects, actions, and spellcasting. It also differentiates itself from get-character-entity by explicitly pointing there for full item/effect data. The verb and resource are specific enough that an agent can identify what this tool does at a glance.

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 explains the identifier resolution behavior and names get-character-entity as the alternative when full item/effect data is needed. It also tells the agent when results will be minimal ('Without an adapter for the game system only name, type and image are known'), setting expectations for sparse output. It does not enumerate all possible sibling alternatives like list-characters, so the routing guidance stops just short of exhaustive.

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