BLACK SOULS MCP
Server Quality Checklist
Latest release: v1.10.0
- Disambiguation5/5
Each tool has a clearly distinct purpose, covering process management, state inspection, input, memory, goals, navigation, battle, and dialogue. Even tools like black_souls_get_state and black_souls_situation differ in detail and focus.
Naming Consistency5/5All tools consistently follow the verb_noun pattern with the 'black_souls_' prefix, e.g., black_souls_kill, black_souls_get_state, black_souls_input_sequence. The naming is uniform and predictable.
Tool Count4/5With 36 tools, the set is comprehensive and each tool serves a specific purpose for game interaction. While it is on the higher end, the complexity of the game justifies the number. A slight reduction could still maintain completeness.
Completeness5/5The tool set covers all major game operations: launch/stop, state reading, input, save/load, navigation, battle, dialogue, memory/goals, and evaluation. There are no obvious gaps for the intended use case.
Average 3.6/5 across 36 of 36 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 29 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and destructiveHint=false. The description adds no additional behavioral context, such as how updates work, conflict resolution, or any side effects. It does not contradict annotations, but adds minimal value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but too brief to be informative. It lacks structure and detail, yet does not contain unnecessary verbiage. It earns a passing score for brevity but loses points for inadequate completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five required parameters, no schema descriptions, and an existing output schema, the description is severely incomplete. It does not explain the function of each parameter or the tool's behavior in different scenarios. The agent cannot properly invoke the tool based solely on this description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about the five required parameters (key, value, source, category, confidence). Since schema description coverage is 0%, the description fails to compensate, leaving the agent with no guidance on what each parameter means or how to use them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool stores or updates a long-term game knowledge entry, which is a specific verb and resource. It distinguishes from sibling tools like black_souls_memory_read and black_souls_memory_delete by implying write operations, but does not explicitly differentiate or name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., scratchpad_write or session_log_append). The description only states what it does, not when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is read-only false and not idempotent, but the description does not disclose potential side effects like log size limits, ordering guarantees, or whether the append overwrites existing entries. It merely restates the operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5Is the description appropriately sized, front-loaded, and free of redundancy?
While the single sentence is concise, it omits essential details. The description is under-specified for a tool with 4 parameters and no schema descriptions, making it inefficient for correct agent usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the game context and the lack of annotation support, the description fails to provide sufficient context. It does not explain the purpose of the session log, how it differs from other storage tools, or when an event is considered 'significant'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must explain the parameters. It does not mention 'event_type' enum values, the meaning of 'frame' and 'scene', or constraints on 'summary'. No examples or clarifications are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Append') and the target resource ('persistent session log'). It distinguishes the tool from its sibling 'black_souls_session_log_read', which performs the opposite operation. The qualifier 'significant gameplay event' adds specificity to the intended use.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as scratchpad or memory writes. There is no mention of prerequisites, when not to use it, or how it fits into a typical workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the tool is safe and non-destructive. The description adds the context of blocking ('before proceeding'), but does not explain polling behavior, potential delays, or failure cases (e.g., timeout). The timeout parameter is not mentioned in the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one sentence, but it omits essential parameter and behavioral details that would improve usability. While front-loaded with purpose, it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (multiple condition types, a timeout parameter, blocking behavior) and that an output schema exists, the description is insufficient. It does not list condition types or explain how to use timeout, leaving the agent uninformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate by explaining parameter meanings. It does not mention 'condition' or 'timeout_ms', nor the various condition types (scene, not_scene, battle_end, etc.). The description adds no semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'wait' and the resource 'game condition', making the core purpose clear. It distinguishes itself from sibling tools like black_souls_get_state by signaling that it blocks until a condition is met, though it could specify the condition types available.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., polling with get_state or using other triggers). The description does not mention prerequisites, exclusions, or recommended scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds no behavioral context beyond what annotations provide. It does not disclose whether updates are full-replacement or merge, nor any side effects like overwriting existing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, very concise with no filler. However, it could be slightly longer to include minimal additional context while remaining efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 required parameters and zero schema descriptions, the description is severely incomplete. It does not mention the output schema, which is present according to context. The tool's complexity demands significantly more detail for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any of the 8 required parameters. The agent has no guidance on what values to provide for id, title, description, status, priority, parent_id, completion_condition, or notes beyond the schema constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create or update a persistent gameplay goal.' It uses a specific verb and resource, distinguishing it from sibling tools like black_souls_goals_read (reading) and black_souls_goals_set_active (setting active goal).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description implies usage when creating or updating a goal, but does not provide context for when to choose this over other goal-related tools, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no hints (all false), so description should disclose side effects. It does not explain what happens if no dialogue is active, if timeout occurs, or the outcome of advancing beyond dialogue end. Only implies mutation and progression.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is maximally concise and front-loaded, containing core functionality without fluff. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists but is not described, the description omits return values, error scenarios, and behavior on dialogue termination vs choice appearance. For a tool with many siblings, this leaves important gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. Description only correlates 'choice_index' to 'selecting a choice' implicitly, but does not explain 'timeout_ms' (e.g., max wait per advance) or 'max_advances' (e.g., number of line skips). Agents would need to infer their purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'advance' and the resource 'active dialogue', specifying it continues until dialogue ends or a choice appears, with optional choice selection. This distinguishes it from sibling tools like black_souls_input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like input sequences or when to avoid it. No prerequisites mentioned, e.g., ensuring dialogue is active.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds that inputs are 'allowlisted' and injected into the 'normal game input loop,' but lacks details on side effects, execution timing, or error conditions. Minimal additional 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that delivers the core purpose without extraneous words. Highly efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema (which partly alleviates return value explanation), the description leaves parameter semantics and behavioral details largely unexplained. Given 3 parameters and no schema descriptions, the tool description is too sparse for complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters with no descriptions (0% coverage). The description does not explain any parameter meaning beyond 'one allowlisted input.' No value added over the enum list and integer ranges.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('inject') and resource ('normal game input loop'), specifying it's a single allowlisted input. This distinguishes it from sibling tool 'black_souls_input_sequence' which handles multiple inputs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for single inputs but does not explicitly state when to use this over alternatives like 'black_souls_input_sequence' or when not to use it. The context of sibling tools provides some inference, but no direct guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint true and destructiveHint false, setting expectations for safety. The description adds no additional behavioral context beyond the verb 'delete', but is consistent and minimally adequate given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence that is front-loaded and contains no redundant information; every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the description lacks usage context, parameter semantics, and error scenarios, making it incomplete for a tool that is part of a large set of memory-related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the parameters 'key' or 'category' at all, leaving the agent without guidance on valid values or formats beyond the enum for category.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool deletes a long-term memory entry using a specific verb ('delete') and resource ('long-term memory entry'), distinguishing it from siblings like memory_read and memory_write.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like memory_read or memory_write. No prerequisites, consequences, or error handling mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide minimal info (all false). The description says 'Update' but does not clarify whether writes overwrite or merge, nor the behavior of optional parameters. No mention of persistence or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 10 words conveys the core purpose without extraneous text. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 optional parameters (one nested) and many sibling tools, the description lacks context on interaction with scratchpad_read, session scope, and overwrite behavior. An output schema exists but is not available to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. While the description maps 'notes' and 'flags' to the respective parameters, it does not explain their semantics (e.g., flags are boolean keys). The 'append_action' parameter is only partially described as 'recent actions' with no details on frame, action, result.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates the session scratchpad, listing specific fields (notes, flags, recent actions). It distinguishes from siblings like scratchpad_read (read) and memory_write (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., scratchpad_read for reading, memory_write for memory). The description does not mention exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that it reads the 'most recent' entries and that the log is 'persistent', providing some additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no extraneous words. It efficiently conveys the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description is too minimal. It omits parameter semantics and does not specify behavior like ordering or limits, making it insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain the sole parameter 'last_n' or its effect (e.g., number of entries to read). With 0% schema description coverage, the tool description should compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads the most recent persistent session log entries. The verb 'read' and resource 'persistent session log entries' are specific and distinct from sibling tools that append to the log or read other logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like scratchpad_read or memory_read. There is no mention of appropriate contexts or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotations false, description carries full burden but only says 'walk up to and interact', not disclosing side effects, whether it changes game state, or what constitutes an event. No mention of movement blocking or confirmation dialogs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no fluff. Every word adds value. However, it may be under-specified given the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the game's many sibling tools and the presence of an output schema, the description is too minimal. It does not specify what happens when no ID is given (nearest event?), what the output represents, or how timeout interacts with the action. Incomplete 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.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage 0% so description must compensate. Adds meaning for 'event_id' ('optionally selected by ID') but provides no explanation for 'timeout_ms', leaving its purpose unclear despite schema constraints (2000–60000).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
Describes a specific verb ('interact') and resource ('event'), and adds 'walk up to' indicating movement. It is clear but does not differentiate from sibling tools like 'black_souls_advance_dialogue' or 'black_souls_battle_action' which are also interactions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Mentions optional selection by ID, implying use when you want to interact with a specific event. No explicit guidance on when to use this versus alternatives like dialogue or battle actions, leaving context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context about minimized window preventing keyboard leakage and input working via background wake path. However, lacks disclosure of idempotency, error handling, or state if already launched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then behavioral detail. No redundancy, but could be more structured for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key launch behavior and input path, but missing parameter explanations and usage context. Output schema exists but description doesn't reference it or expected return.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage; description does not mention wait_ms or minimize_window parameters, leaving their purpose and format unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool launches the BLACK SOULS MCP edition and waits for its in-game bridge. Distinguishes from sibling tools like black_souls_kill by targeting a distinct action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage via description of default minimization behavior, but does not explicitly state when to use versus alternatives or prerequisites. No exclusions or context for calling multiple times.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety profile is clear. The description adds 'directly from RGSS3' but lacks further behavioral context (e.g., performance, refresh behavior).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. However, it could benefit from structuring the output items more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless tool with an output schema, the description is mostly adequate. Lacks mention of the 'nearby' range, but the output schema likely covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so baseline is 4. No additional parameter meaning needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads nearby map tiles, passability, and events from RGSS3. However, it does not explicitly differentiate from sibling tools like get_full_map or get_event, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No comparison with get_full_map or other map-related tools, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, making the non-destructive nature clear. The description adds that the tool provides 'diagnosis and recommended recovery action,' implying a read-only analysis. However, it does not elaborate on side effects, prerequisites, or edge cases, so it adds only modest value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that succinctly captures the tool's purpose and output. It is front-loaded with no redundant or extraneous content, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description is largely complete. It explains the core function and expected return (diagnosis and action). However, it could briefly clarify the domain context (e.g., what 'bridge' refers to) to aid agent comprehension without burdening the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no parameters, so the description provides no parameter details—which is appropriate. With 0 parameters, a baseline of 4 is justified as no further semantic explanation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a 'bridge health check with diagnosis and recommended recovery action.' This differentiates it from siblings like black_souls_status (general status) and action-oriented tools. However, it does not explicitly contrast with similar read tools, and the term 'bridge' is left unexplained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as black_souls_status or black_souls_get_state. The description lacks contextual cues for appropriate invocation, leaving the agent to infer usage without explicit boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is safe. The description adds that it reads 'long-term game knowledge', which implies persistence, but it does not detail behavioral traits like return format or performance characteristics. Given annotations carry the safety burden, the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the core action ('Read long-term game knowledge') and includes the key optionality. No wasted words; every element contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (not shown) and annotations cover safety, the description is mostly complete for a read operation. However, it could explicitly mention the output format or the scope of 'long-term' (e.g., persists across sessions). The missing category descriptions reduce completeness slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The description mentions 'optionally filtered by category' but does not list the enum values or explain what each category (map, npc, etc.) signifies. The schema provides the enum, but the description lacks explanatory value beyond the existence of a filter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Read long-term game knowledge, optionally filtered by category.' This is a specific verb-resource pair that clearly distinguishes from sibling tools like black_souls_memory_write (write) and black_souls_scratchpad_read (short-term memory).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus other read-focused siblings (e.g., black_souls_get_variables, black_souls_get_inventory). The description does not mention when not to use or provide context for selecting this over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (readOnlyHint=false, etc.). The description mentions 'automatic pathfinding over current passability data,' hinting at behavior like obstacle avoidance and map constraints, but does not explain failure cases, timeout behavior, or state changes beyond movement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single efficient sentence that conveys core purpose and behavior. However, it could be slightly more informative about parameters without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description may not need to detail return values. However, it lacks information on preconditions (e.g., must be on a valid tile) and postconditions, which limits completeness for a navigation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description does not explain any parameters (x, y, timeout_ms). The agent must infer that x and y are coordinates and timeout_ms is optional. The description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Move'), resource ('target tile'), and method ('automatic pathfinding'). It distinguishes from sibling tools like black_souls_kill or black_souls_input by focusing on navigation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for movement but does not specify when to use it versus alternatives (e.g., battle actions, interactions). No explicit when-not-to-use context or sibling comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns pass/fail per condition, which is consistent and provides modest additional detail 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no redundant words. The first sentence states the action, the second provides context and outcome. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose and return type, and an output schema presumably details the return structure. However, it omits any explanation of the input parameter structure, which is complex with nested objects and conditional fields. Given the tool's specificity to eval scenarios and the presence of an output schema, the description is moderately complete but has a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention the 'check_conditions' parameter. With 0% schema coverage, it is critical for the description to explain the parameter structure, but it fails to do so. The agent must rely solely on the schema, which has enum types and conditional fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'check' and resource 'scenario completion conditions', clearly distinguishing from sibling status tools like black_souls_status. The mention of 'used by the eval runner' provides context and differentiates it as an evaluation-specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states it is used by the eval runner and returns pass/fail, implying it is for automated scenario completion checks. However, it does not explicitly exclude other use cases or provide alternative tool names for general status queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds specific behavioral context on what is inspected (pages, triggers, self-switches), enhancing transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that conveys essential information without redundancy. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description does not need to detail return values. It lists key inspected components but omits context about what an 'event' is in the game world, leaving some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, it does not mention the required parameter 'event_id' or explain its meaning, leaving the agent without additional context beyond the schema's technical constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool inspects an event's pages, trigger conditions, active page, and self-switches, using a specific verb and resource. It distinguishes itself from sibling tools by focusing on event inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor does it mention prerequisites or contexts. With 30+ sibling tools, this omission limits the agent's ability to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide read-only and idempotent behavior. The description adds minimal additional behavioral context beyond stating it reads 'deeper state', which is consistent with annotations. No contradiction, but little extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one clause), no redundant information. It is front-loaded and efficient, though slightly vague. Could be improved by specifying what 'deeper state' entails.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, rich annotations, and the presence of an output schema (not shown), the description adequately sets expectations for a read-only tool. It mentions the three relevant scene types (map, battle, menu). The term 'deeper' suggests detail not captured in simpler state tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the description does not need to clarify parameters. However, it adds semantic value by specifying the scope (active scene), which is useful context for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'deeper state for the active map, battle, or menu scene'. It distinguishes from sibling tools like get_state or get_map by focusing on 'deeper state' and specific scene types, though the exact meaning of 'deeper' remains somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidelines on when to use this tool versus alternatives. The description implies it is for obtaining detailed state of the current scene, but it does not contrast with related tools like black_souls_get_state or black_souls_get_map, leaving the agent to infer the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, which are not contradicted. The description adds the fact that the tool returns the resulting state, but does not elaborate on side effects (e.g., overwriting current progress) or prerequisites. With limited annotation detail, the description provides moderate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no redundancy. It is front-loaded and efficiently communicates the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately conveys the tool's function but lacks parameter details, which could lead to misuse. Given the existence of an output schema, the return value explanation is not required, but the absence of parameter guidance makes it only moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not mention 'slot' or 'timeout_ms' at all, offering no additional meaning beyond the raw schema types and ranges.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (load), the resource (save slot), and the context (from title screen or in-game menu), and mentions the output (return resulting state). This distinguishes it from siblings like black_souls_save or black_souls_list_saves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to load a save slot) but does not explicitly state when not to use it or list alternatives. However, the context of sibling tools provides implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, which fully cover the tool's behavioral safety. The description adds no behavioral information beyond what is already in annotations, so it meets the baseline without adding extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately communicates the tool's purpose with no extraneous words. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, an output schema exists, and annotations cover safety, the description is sufficiently complete for a simple status inspection. However, mentioning that it is safe to call at any time would slightly improve context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description does not need to add parameter meaning, and it correctly focuses on the tool's purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'inspect' and identifies the resources ('BLACK SOULS MCP edition and live RGSS3 bridge status'), which clearly conveys what the tool does. It distinguishes from sibling tools that perform actions like launch, kill, or state retrieval, but could be more specific about what 'status' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for checking system status but does not explicitly state when to use this tool versus alternatives like black_souls_get_state or black_souls_health. No when-not-to-use guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true and idempotentHint=true. The description adds 'without modifying them' but does not disclose additional behavioral traits such as ordering, number of saves returned, or authorization requirements beyond what annotations imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise and front-loaded with the key action. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, rich annotations, and an output schema (not shown), the description covers the essential purpose and non-modifying behavior. It could mention what metadata is returned but is otherwise complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description does not need to explain parameter meanings. The baseline for 0 params is high, and the description is clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'independent MCP-edition save slots and metadata'. It distinguishes from siblings like black_souls_save (write) and black_souls_load (load) by emphasizing it does not modify data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternatives are provided, but the name and context of siblings imply it is for inspecting saves before loading or deleting. Lacks guidance on when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds marginal value by noting 'directly from RGSS3', implying raw memory access. No contradictions or additional behavioral notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 14 words, front-loaded with verb and resource, no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, an output schema present, and annotations covering safety, the description adequately lists what components are read. No further information needed for a read-only state dump tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters, meaning 100% schema coverage. Description adds no further parameter info, but baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Read' and lists exact resources (scene, player, party, etc.) directly from RGSS3. This clearly distinguishes from sibling tools like black_souls_status which might provide a summary, and black_souls_get_scene_detail which is more focused.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like black_souls_status or black_souls_get_scene_detail. The description only states what it does, leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide no hints, so the description adds value by disclosing closed-loop menu navigation and upfront cost validation, which are important behavioral traits beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the core purpose, and every sentence provides essential information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While output schema is present, the description lacks details on parameter roles and does not elaborate on the return format beyond stating returned state. Given the tool's complexity, more context would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain parameters like item_index, timeout_ms, enemy_index, and skill_index. It only alludes to 'list index' and 'enemy target' generically, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes one battle turn with a specific action, referencing sibling black_souls_battle_options for indices. It distinguishes itself as the action executor among battle-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies the prerequisite of black_souls_battle_options for indices and mentions refusal of unaffordable choices, but does not explicitly state when to use this over other tools like black_souls_interact or black_souls_input.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive behavior. The description adds important performance context (radius 6 is cheap, radius 20 freezes the game), which goes beyond annotations and helps the agent understand runtime impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences only: the first states the purpose, the second provides a critical performance warning. Every sentence adds value; no excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present (not shown), the description covers the returned data types and performance trade-offs. For a single-parameter tool with clear annotations, this is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must explain the parameter. It does so by linking radius to performance cost and limitations, adding semantic value that is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves map tiles, passability, regions, terrain tags, and events within a radius. It provides a specific verb ('request') and resource ('full map'), though it does not explicitly differentiate from siblings like black_souls_get_map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when map data is needed) and includes a performance recommendation ('prefer 12 or less'), but does not state when not to use or provide alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive. Description adds that result includes counts per item category but does not detail return format or edge cases. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, 14 words, front-loaded with action. No redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with no parameters. Output schema exists. Description covers main categories of items. Minor omission: no mention of counts display or sorting, but overall complete for a read-only inventory tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has zero parameters; schema coverage is 100% trivially. Baseline score of 4 is appropriate per rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Read', resource 'party's current inventory', and specific item types (consumable, weapons, armors with counts). Distinguishes from sibling tools like black_souls_get_state and black_souls_get_party_detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance, nor mention of alternatives. However, the tool's purpose is self-evident for inventory retrieval, making implicit usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds the constraint on the number of IDs per call, but does not disclose return format or behavior for invalid IDs. Since annotations cover the core behavioral traits, the description adds marginal value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences that immediately convey the purpose and a key constraint. Every word is necessary; no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, output schema exists, annotations rich), the description covers the essential purpose and constraint. It does not explain scenarios like missing IDs, but the output schema likely handles that. Overall complete enough for context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'by ID' and 'up to 64 IDs per call', providing some context for the single parameter 'ids'. However, with schema description coverage at 0%, the description could more explicitly explain that the parameter is an array of integers in the range 1-9999. It adds meaning but is not fully compensatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'RPG Maker game variable values', and a key constraint 'by ID' and 'Request up to 64 IDs per call'. It distinguishes from siblings like black_souls_get_switches (which reads boolean switches) and black_souls_memory_read (which reads arbitrary memory).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for reading variable values by ID, and gives a constraint on the number of IDs per call. It does not explicitly state when to use this tool versus alternatives, but the naming context and sibling names provide sufficient differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-read-only and non-destructive. The description adds that it injects inputs, which is consistent. However, it does not disclose additional behavioral traits such as execution order guarantees, whether actions are atomic, or any side effects beyond injection.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the core purpose. It contains no fluff and earns its place by immediately informing the agent of the tool's key capability and constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (array of mixed objects, 2 parameters, sibling tools) and the presence of an output schema, the description is sufficiently complete. It explains the core function. Minor omission: does not explicitly state that steps are executed sequentially, but this is implied by 'ordered sequence'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds high-level meaning ('allowlisted inputs and frame waits') but does not detail the specific actions (already in schema enums) or explain parameters like 'repeat' or 'timeout_ms'. The description provides context but not full clarity for all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it injects up to 200 allowlisted inputs and frame waits as an ordered sequence. It uses specific verbs ('inject') and resources ('allowlisted inputs', 'frame waits'), and the name 'input_sequence' distinguishes it from single-input tools like black_souls_input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when multiple sequential inputs are needed, up to 200. It does not explicitly state when not to use it or mention alternatives, but the sibling tool names (black_souls_input, black_souls_wait) provide clear context for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by revealing that the tool injects menu navigation inputs, which is a key behavioral trait. Annotations do not contradict, but the description could further clarify whether the save overwrites the slot.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each essential. Front-loaded with the core action and constraint. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description provides a critical constraint (Scene_Map) and basic purpose, it lacks explanation of the 'timeout_ms' parameter, error handling if not on Scene_Map, and return value details (though output schema may cover that). Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only clarifies that the 'slot' parameter is 0-indexed. It does not explain the 'timeout_ms' parameter, leaving it ambiguous. This partial compensation is insufficient for a tool with 2 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool triggers an in-game save to a specific slot by injecting menu navigation inputs. It distinguishes itself from siblings like load and list_saves by specifying the action and the constraint 'Only works from Scene_Map.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool only works from Scene_Map, providing a clear usage context. However, it does not explicitly mention when not to use it or provide alternatives (e.g., load for loading saves).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering safety and side effects. The description adds no behavioral details beyond stating it reads the scratchpad, which is consistent with annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of 9 words. Every word contributes meaning without any filler, making it maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an existing output schema, the description is largely sufficient for a simple read tool. It could potentially specify what exactly is returned (e.g., 'entire scratchpad content'), but the output schema likely covers this, so the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so schema description coverage is 100% trivially. The description does not need to add parameter semantics. Baseline 4 applies as per guidelines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the resource ('the AI agent's current session scratchpad'). This distinguishes it from sibling tools like black_souls_scratchpad_write and other read tools (memory, goals).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool vs. alternatives, such as black_souls_memory_read or black_souls_goals_read. However, the sibling names and context imply its purpose. No usage restrictions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, so no contradiction. The description adds that the tool sets or clears the active goal, which is consistent. However, it does not detail requirements (e.g., goal must exist) or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, concise and front-loaded with the essential action. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with one parameter, the description covers the core behavior completely. The existence of an output schema means return details are not needed. Annotations fill in idempotency and safety traits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains that the 'id' parameter identifies the goal to set, and that null clears it. This adds meaning beyond the schema's type definition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('choose' or 'clear') and the resource ('gameplay goal'), and it distinguishes from sibling tools like black_souls_goals_read and black_souls_goals_write by specifying the action of setting the active goal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (when you want to set or clear the current goal) but does not explicitly state when not to use or mention alternatives. It provides clear context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds context about content (snapshot, suggestions, warnings) but does not contradict annotations. No additional behavioral traits are disclosed 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 12 words, front-loaded with 'Get a concise snapshot'. Every word is meaningful and there is no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists, the description adequately explains the three components (snapshot, suggestions, warnings). No additional context is necessary for this simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the schema coverage is 100%. No parameter information is needed in the description; baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a concise snapshot of the current game situation, along with contextual action suggestions and warnings. It uses specific verb 'Get' and resource 'game situation', distinguishing it from siblings like status or get_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for obtaining an overview with suggestions and warnings, but does not explicitly state when to use this tool versus alternatives like black_souls_status or black_souls_get_state. No when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds 'persistent' and 'hierarchy' but does not elaborate on output format or behavior beyond that. Minimal additional value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with verb first, no filler, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and that an output schema exists, the description suffices. It does not explain return value structure, but that is covered by the output schema. Some context about what 'persistent' means could be added, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description cannot add meaning beyond the schema. Baseline for 0 parameters is 4 because no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the specific resource 'persistent objective hierarchy and active goal'. It is distinct from siblings like black_souls_goals_write and black_souls_goals_set_active, which cover write and set operations respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance, but the tool's read-only nature and zero parameters imply that it should be used to retrieve goal state. Since there are no alternative read tools among siblings, the usage is clear by exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the batch limit (64 IDs) and confirms the tool reads boolean switches, providing useful behavioral 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, schema covers all constraints, annotations cover safety, and an output schema exists. The description is complete and informative for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the single parameter 'ids' is explained by the description stating 'by ID' and the batch limit, adding meaning to the array of integers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read RPG Maker boolean switches by ID', which is a specific verb and resource. It clearly distinguishes from sibling tools like black_souls_get_variables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions a batch limit of 64 IDs, which provides usage context, but does not explicitly state when to use this tool over alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds value by specifying 'forcefully terminate' (indicating abruptness) and explicitly stating safety when game is not running, which clarifies idempotency beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long with no extraneous information. Every word serves a purpose: defining the action and clarifying safety.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, clear destructive and idempotent behavior), the description fully covers what the agent needs to know: what it does and that it is safe to call when the game is not running.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema description coverage is 100% (trivially). The description does not need to add parameter information; the baseline of 3 is appropriately increased to 4 because there are no parameters to explain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'forcefully terminate the running BLACK SOULS process.' The verb 'terminate' and resource 'running BLACK SOULS process' are specific and distinct from sibling tools like launch or status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a safety note 'Safe to call when game is not running,' implying idempotency. However, it does not provide explicit guidance on when to use vs. alternatives (e.g., graceful shutdown) or context for typical use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so no side effects. The description adds useful context about the returned data (stats, equipment, skills), enhancing understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with eight words that directly state the tool's function, with no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema and the tool's simplicity (no parameters), the description provides complete context about its purpose and return value, requiring no additional elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage (vacuously), the description adds valuable meaning by explaining what the tool returns, going well beyond the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads party details (stats, equipment, skills) and distinguishes it from siblings like black_souls_get_inventory, black_souls_get_state, and black_souls_get_event, which focus on other aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for party information but does not explicitly state when to use this tool over alternatives, nor does it provide any exclusions or context about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, which are consistent with the description. The description adds valuable behavioral detail: that every entry carries an exact index for use with black_souls_battle_action, going 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the tool's main purpose. Every part earns its place: the first sentence lists contents, the second explains the utility of indices. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no parameters and an output schema, the description comprehensively explains the output: top-level commands, full skill/magic details (including costs and usability), battle items, and enemy targets. This makes the tool's behavior fully clear for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage, the description correctly adds no parameter semantics. The baseline for 0 params is 4, and the description appropriately focuses on what the tool returns instead.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List everything the acting battler can do this turn' and details the contents (top-level commands, skills, magic, items, enemies). It clearly distinguishes from sibling tools like black_souls_battle_action by stating its purpose as a prerequisite for that action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'call this before choosing a battle action instead of guessing,' providing clear when-to-use guidance. It does not explicitly mention when not to use it, but the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/yk4464/black-souls-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server