cozyvtt-mcp

Creature Search

creature_search

Read-onlyIdempotent

Search creature library templates for later token placement. Filter by name, challenge rating, or source; returns read-only results for DMs.

Instructions

Search library templates for later placement with token_place_creature. Use character_list for campaign character sheets; this does not create either a character or a token. Read-only for campaign members. Explicit srd requires DND_5E; custom works across systems; v1.5.0 restricts creature library reads to the DM. Empty source searches both in DND_5E and custom otherwise. Search, challenge rating and offset are forwarded; limit is capped at 100 without local lower-bound validation. Repeating a search leaves the library unchanged. Returns {ok:true,data} on success; tool-body failures return {ok:false,error} with optional diagnostic data. Argument-schema errors are MCP errors.

Input Schema

Name	Required	Description
`cr`	No	Challenge-rating filter passed as text, for example 1/2 or 3; empty omits it. Applicability is upstream-defined.
`limit`	No	Requested page size, normally 1..100; defaults to 20. Values above 100 are capped; other validation is upstream.
`offset`	No	Number of search results to skip, normally >=0; defaults to 0. Forwarded without local range validation.
`search`	No	Name/search filter passed upstream; empty string omits the filter.
`source`	No	srd or custom (case-insensitive); empty chooses both for DND_5E and custom for other or flexible campaigns.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.3.0Sep 20, 2026

addedInput schema / properties / cr / description

Added value: +"Challenge-rating filter passed as text, for example 1/2 or 3; empty omits it. Applicability is upstream-defined."

addedInput schema / properties / limit / description

Added value: +"Requested page size, normally 1..100; defaults to 20. Values above 100 are capped; other validation is upstream."

addedInput schema / properties / offset / description

Added value: +"Number of search results to skip, normally >=0; defaults to 0. Forwarded without local range validation."

addedInput schema / properties / search / description

Added value: +"Name/search filter passed upstream; empty string omits the filter."

addedInput schema / properties / source / description

Added value: +"srd or custom (case-insensitive); empty chooses both for DND_5E and custom for other or flexible campaigns."

First observedv0.1.0Sep 5, 2026

TDQS

A4.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful version/auth context (DM-only reads in v1.5.0) and the return/error contract ({ok:true,data}, {ok:false,error}, MCP schema errors), but much of the 'does not mutate' framing restates idempotentHint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and the alternative tool, then dense behavioral notes. Every clause carries information, though the single dense paragraph mixes usage, versioning, parameter and error details without much structural separation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema, annotations, and 100% parameter coverage, the description supplies the remaining operational context: cross-system source resolution, the v1.5.0 DM restriction, forwarding/capping behavior, and error-shape distinctions. Nothing an agent needs before calling is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by disclosing forwarding semantics ('search, challenge rating and offset are forwarded'), the hard cap at 100 without local lower-bound validation, and the cross-system behavior of an empty source.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search library templates') and ties it to the downstream sibling token_place_creature, which disambiguates it from character_list immediately. An agent can tell what it retrieves and why without reading the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: 'Use character_list for campaign character sheets; this does not create either a character or a token.' It also names the version-specific access rule (v1.5.0 restricts library reads to the DM) and the empty-source behavior, giving concrete when/when-not conditions.

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