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

Annotations provide openWorldHint and idempotentHint, but no readOnly/destructive hints. The description adds valuable behavioral context: it returns 'the new actor UUID and document,' is restricted to dnd5e worlds, and warns that the attack schema targets dnd5e v5.2.2 activities model with advice to verify against a live NPC. These details go beyond what annotations convey.

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 long, front-loaded with the core purpose and action. The warning about the attack schema is necessary and concise. Every sentence earns its place without redundancy.

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?

For a tool with 17 parameters, nested objects, and no output schema, the description provides crucial context: the dnd5e-only constraint, return type, and attack schema warning. However, it does not explain the 'friendly schema' terminology or edge cases like duplicate names or non-idempotent behavior beyond the annotation. It is fairly complete for a complex tool but leaves some questions unanswered.

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 53%, so a significant portion of parameters lack explicit descriptions. The tool description does not explain any specific parameters; it only calls the schema 'friendly' and mentions the attack schema caveat. It does not compensate for undocumented nested structures like abilities, speeds, or senses, offering minimal added value beyond the schema.

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 clearly states 'Build a dnd5e 5th-edition NPC actor from a friendly schema and create it in Foundry.' This specifies the action (build/create), resource (dnd5e NPC actor), and differentiates from generic sibling tools like foundry_create_entity by being dnd5e-specific. The title 'Create dnd5e NPC' reinforces the purpose.

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 gives a clear precondition: 'Only available when the connected world is dnd5e.' This implies the tool is intended for dnd5e worlds and NPC creation. However, it does not explicitly mention alternatives like foundry_create_entity for non-dnd5e scenarios, so it lacks explicit when-not guidance.

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

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

The description confirms it creates a new entity and returns the new UUID/document, consistent with openWorldHint=true and idempotentHint=false. However, it doesn't detail what happens to existing data, permission requirements, or failure modes beyond what annotations already imply. Minimal added context beyond the annotations.

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?

Two concise sentences, front-loaded with the action, and no redundant information. Each word adds value, and it efficiently communicates purpose and return value.

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?

The schema and annotations handle many details, and the description states the return value. However, it lacks guidance on when to use this vs. sibling create tools, and it doesn't mention edge cases like override behavior or folder constraints, making it adequate but not complete.

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 only repeats 'raw Foundry document' in the body, which mirrors the schema's data parameter description. It adds no extra insight into folder, override, or userId semantics beyond what the schema already provides.

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?

Clearly states it creates a new Foundry entity with a raw Foundry document and lists supported types (Actor, Item, JournalEntry). The verb 'create' and resource 'Foundry entity' are specific, and it differentiates from siblings by focusing on raw document creation and returning a UUID.

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 for creating entities, but offers no explicit comparison to alternatives like foundry_create_creature or foundry_update_entity. It provides no when-not guidance or exclusions, leaving the agent to infer when this raw-document approach is preferred over specialized creation tools.

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

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

The annotations already flag destructiveHint: true, but the description adds valuable context by stating the deletion is 'Permanent' and 'irreversible.' It also discloses that the operation can target by UUID or current selection, going beyond the bare annotation to convey the action's finality and flexibility.

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 two succinct sentences that front-load the action and key detail (UUID or selection). Every word earns its place; there is no redundant information or filler.

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?

The tool is straightforward, supported by full schema coverage and the destructiveHint/openWorldHint annotations. The description adds the critical fact of irreversibility. It doesn't delve into side effects like child deletions, but for a simple delete operation, the covered points are sufficient.

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 mentions 'by UUID or current selection,' which aligns with the uuid and selected parameters, but adds no further meaning beyond what the schema already documents. No additional insight is provided for userId or clientId overrides, so the baseline score stands.

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 clearly states the tool's function: 'Permanently delete a Foundry entity by UUID or current selection.' This specifies the verb (delete), resource (Foundry entity), and method (by UUID or selection), distinguishing it from sibling tools like create, update, and search.

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 provides clear context for when to use the tool (when you want to delete an entity) and the two ways to target it (UUID or current selection). It does not explicitly cite alternatives, but the purpose is unmistakable given the tool name and sibling set, meeting the 'clear context, no exclusions' criterion.

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

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

With annotations already indicating readOnlyHint=true and openWorldHint=true, the description adds useful context by stating the return value includes the full document with system data and embedded items. It also clarifies the selected token/actor behavior, increasing transparency beyond the annotations.

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 two sentences, front-loaded with the primary purpose followed by return details. Every word earns its place; no redundancy or fluff.

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?

For a read-only retrieval tool with no output schema, the description sufficiently explains what it returns (full document, system data, embedded items) and its two modes (UUID or selected). It does not over-explain, but given the simplicity and annotations, it is complete enough for an agent to use effectively.

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 input schema already has 100% coverage with descriptions for all five parameters. The tool description adds minimal extra meaning—it mentions 'by UUID or selected' which aligns with the uuid and selected params, but does not further elaborate on parameter behavior or format. Baseline 3 is appropriate given high schema coverage.

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 clearly states the tool retrieves a Foundry entity by UUID or the currently selected token/actor. This uses a specific verb ('Retrieve') and resource ('Foundry entity'), and the two modes distinguish it from sibling tools like delete, create, and update.

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 conveys clear usage context: use it to get an entity by UUID or selected token/actor. It does not explicitly mention alternatives, but the sibling tool names (e.g., foundry_search, foundry_update) imply when this read-only retrieval tool is appropriate. No exclusions are stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat safety. It adds value by disclosing the return fields (online status, system, version info), which is useful behavioral context. However, it doesn't go into detail about pagination or error behavior, but given the simplicity of the tool, this is adequate.

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 a single, well-structured sentence that immediately states the tool's purpose and the key output data. It is front-loaded with the action and resource, with no filler or redundant content.

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?

For a simple list tool with no parameters, the description fully conveys what is returned (worlds/clients, online status, system, version). The lack of output schema is compensated by the explanation of returned fields. The context of 'connected to the relay' clarifies the scope, making the tool complete.

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 input schema has zero parameters, so the description has no parameter semantics to explain. Baseline for 0 parameters is 4, and the description properly avoids inventing any required arguments. It doesn't add parameter-level detail because none exist.

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 uses a specific verb 'List' with a clear resource 'Foundry VTT worlds/clients connected to the relay'. It distinctly differs from sibling tools like foundry_delete_entity or foundry_search, which handle entities and search operations. The scope is unambiguous.

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 when to use the tool: whenever you need an overview of all connected worlds/clients with their status. It doesn't explicitly mention alternatives or exclusions, but the list operation is naturally distinct from the other CRUD/search tools. The context is clear enough without needing to name alternatives.

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

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

Despite annotations already indicating destructive hint and open world, the description adds valuable behavioral context: the workflow for using the returned uuid, and the limitation that only freshly-created folder UUIDs are known (requiring structure:read for discovery). This goes beyond what annotations provide.

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 two sentences, front-loaded with the core purpose, and adds a valuable usage note and limitation. Every sentence earns its place with no redundant information.

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 the 8-parameter schema and no output schema, the description provides enough context for the main workflow and a key limitation. It could mention more about error cases or return format, but the schema covers parameter details, and the description conveys the essential operational flow.

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 parameters are fully explained in the schema. The description mentions the returned uuid from creation, but doesn't add semantic detail about individual parameters beyond what the schema already provides. Baseline 3 is appropriate.

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 clearly states the tool's function: 'Create or delete a Foundry folder.' This is specific with a verb and resource, and it distinguishes from sibling tools which focus on entities, worlds, and search. No ambiguity.

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 provides clear usage context: after creating a folder, pass the returned uuid as the folder argument when creating entities. It also notes a key limitation about not being able to find existing folders without structure:read, which guides when to rely on freshly-created uuids. It doesn't explicitly name alternatives, but none exist among siblings.

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

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

The description adds one meaningful behavioral detail: 'kill (set HP to 0)' clarifies the exact effect of the kill action. However, it does not disclose other behavioral traits like whether give/remove permanently alter inventories, whether changes are reversible, or whether permissions beyond openWorldHint are required. Since annotations only include openWorldHint, the description carries a moderate transparency burden and meets it only partially.

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 two sentences, immediately lists the core operations, and avoids redundant filler. It is front-loaded with the most critical info and earns its place without unnecessary detail.

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?

Despite the schema covering parameters, the tool is complex with 13 parameters and no output schema. The description does not explain return values, error conditions, or how the action determines required parameters beyond a one-liner. It also omits preconditions like whether the actor must exist or be in the world. For a tool that can kill or remove items, this level of incompleteness is a notable gap.

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 input schema already provides 100% coverage for parameter descriptions, so the description adds little semantic value. It does reinforce that 'action' selects the operation, but the schema already enumerates the actions with descriptions. The mapping between action and parameter groups is handled by bracket prefixes in the schema, not the description, so the description does not significantly enhance parameter understanding.

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 clearly identifies the tool as modifying Foundry actors, listing specific operations (give/remove items, increase/decrease attributes, kill/set HP to 0). This distinguishes it from sibling tools like foundry_delete_entity or foundry_update_entity by focusing on actor mutations rather than entity lifecycle management.

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 phrase 'Use action to select the operation' provides some guidance on how to invoke the tool, but it does not explicitly state when to use this tool versus alternatives such as foundry_update_entity or foundry_create_creature. There is no mention of exclusions or fallback conditions, so the usage context is implied rather than clearly delineated.

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

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

Annotations already provide readOnlyHint and openWorldHint, so the description adds value by specifying the return fields and giving concrete filter examples. This enriches the agent's understanding of behavior without contradicting annotations. It could mention pagination or empty-result behavior, but the additional context is valuable.

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, front-loaded with the primary purpose, and includes a concrete filter example. Every sentence is informative, with no wasted words.

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?

The description covers the essential purpose, return fields, and usage context, which is sufficient given the tool's simplicity and the complete schema annotations. Minor omissions like pagination or error behavior are acceptable for a search tool with read-only annotations.

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?

All parameters have detailed descriptions in the schema, so the description adds little beyond that. The filter example in the description overlaps with the schema description, so the baseline of 3 is appropriate.

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 clearly states it searches for Foundry entities by name and returns UUID, documentType, subType, and package. It also positions itself as 'the primary way to turn a name into a UUID for use with other tools,' which distinguishes it from sibling CRUD tools.

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 explicitly frames the tool's role as the name-to-UUID lookup, giving a clear when-to-use context. It does not name specific alternatives, such as foundry_get_entity, but the implication is present. This is clear context without explicit exclusions.

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

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

Annotations (openWorldHint, idempotentHint) provide some context, and the description adds useful behavioral detail: it is a partial update (only changed fields are sent) and can target either a UUID or the current selection. It does not explain side effects on persisted world data or auth behavior, but with annotations present this is adequate.

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?

Two short, focused sentences. There is no filler or repetition, and the key usage instructions are front-loaded.

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 six parameters, a nested data object, and no output schema, the description is too thin to be fully actionable. It does not explain how uuid and selected interact, when to use actor or userId/clientId, or what the tool returns after an update. The schema lists parameters but the description fails to synthesize them into a coherent usage flow, leaving meaningful gaps.

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 input schema already covers 100% of parameters with descriptions, so the schema carries the heavy lifting. The description reinforces the meaning of 'data' by saying 'only fields to change,' but it does not clarify interactions between uuid, selected, actor, or userId beyond what the schema states, so no significant extra semantic value is added.

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 uses a specific verb ('Update') with a clear resource ('existing Foundry entity') and two targeting modes (UUID or current selection), which immediately distinguishes it from siblings like create, delete, and get. 'Pass only the fields to change' further clarifies the PATCH-like intent.

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 phrase 'existing entity' makes clear it is not for creation or deletion, and 'by UUID or current selection' explains the primary usage modes. However, it does not explicitly mention when to prefer this over foundry_modify_actor or other siblings, so it stops short of full 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.