spoolman-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.0.1
Disambiguation4/5
Most tools have clear, distinct purposes (e.g., list_filaments vs list_materials vs list_article_numbers). Some potential confusion exists between use_spool and measure_spool, or get_info and health_check, but descriptions clarify these differences.
Naming Consistency4/5
Tools generally follow the spoolman_<verb>_<noun> pattern (e.g., list_vendors, create_filament). Minor deviations like health_check (object before verb) and trigger_backup are present but not disruptive.
Tool Count2/5
With 34 tools, the server is well above the typical 3-15 range for coherence. While the breadth covers many Spoolman features, the large number makes it heavy and more complex for agents to navigate.
Completeness3/5
Full CRUD exists for vendors, filaments, and spools, plus exports and settings. However, locations only have list and rename—missing create, delete, and get-by-id—which is a notable gap for that entity.
Average 3.7/5 across 34 of 34 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- No commit activity data available
- Last stable release on March 22, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
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.json to 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?
No annotations exist, and the description adds no behavioral context beyond the name—no mention of permissions, duplicate handling, 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no waste; front-loads the verb and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool, the description does not explain return values, errors, or usage context, and with no annotations or output schema, the description carries full burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters; description adds no parameter semantics, but baseline is 3 since schema documents name and comment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action ('Create a new vendor') with a specific resource and context, distinguishing it from sibling update/delete/get vendor tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 spoolman_update_vendor; no exclusions or scenarios 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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does state the destructive nature ('delete'), but it does not reveal any side effects, reversibility, associated data impacts, or permission requirements. For a delete operation, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that communicates the essential operation without any fluff. It is appropriately sized for a simple parameterization, and the structure is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no annotations and no output schema, the description is incomplete. It does not explain what happens on successful deletion, error conditions, or any side effects. The tool is simple, but the lack of operational context makes it insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage, describing 'id' as 'The spool ID' with an exclusive minimum. The description adds no additional parameter semantics, so with high schema coverage the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a spool by ID' uses a specific verb ('delete') and resource ('spool'), clearly stating the operation. This distinguishes it from sibling delete tools targeting different entities (filaments, vendors, fields).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. There is no mention of prerequisites (e.g., listing spools first) or situations where deletion might be disallowed. The description simply states the action without context.
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 no annotations provided, the description must carry the full behavioral transparency burden, but it merely states 'Set a Spoolman configuration value by key.' It does not disclose whether changes are persisted, if a restart is required, what happens when the key doesn't exist, or if any permissions are needed. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and resource. Every word earns its place, and it is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a setter with no output schema and no annotations, and the description gives no indication of how to discover valid keys (e.g., pointing to spoolman_get_all_settings) or what the consequences of setting a value might be. For a configuration mutation, the context is inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters ('The setting key' and 'The new value to set') with 100% coverage. The description's phrase 'by key' and 'configuration value' aligns with the schema but adds no additional semantic information. This matches the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and resource ('Spoolman configuration value'), clearly distinguishing it from sibling tools like spoolman_get_setting. The phrase 'by key' further clarifies the main input parameter. It fully captures the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 such as spoolman_get_all_settings or spoolman_get_setting. It does not mention prerequisites like looking up valid keys, or any context about which settings can be modified. This leaves the agent with insufficient routing information.
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?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. While 'Retrieve' implies a read-only operation, the description does not state what happens if the key does not exist, whether the response includes metadata, or any potential error behavior. This is a minimal transparency statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and front-loaded. Every word contributes to the tool's purpose, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter getter, the description is functionally sufficient but lacks detail about the return format (e.g., whether it returns a plain value or an object) and error handling. Since there is no output schema and no annotations, these omissions are notable, though the simplicity of the operation keeps it from being incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter 'key' is 100%, and the description simply restates 'by key' without adding new semantics. The baseline of 3 is appropriate because the schema already describes the parameter fully; no additional context is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Retrieve') and clear resource ('Spoolman configuration setting') with a method ('by key'), making the tool's function immediately obvious. It also distinguishes itself from siblings like spoolman_get_all_settings by noting 'single'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance about when to choose this tool over alternatives such as spoolman_get_all_settings or spoolman_set_setting. It does not mention contexts where a single setting is needed, nor does it exclude use cases.
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?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It only mentions that density and diameter are required, which is already in the schema. It does not disclose side effects, idempotency, authentication needs, or what happens after creation (e.g., return value, errors).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core action. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 15-parameter tool with no output schema and no annotations, the description is too sparse. It does not explain return values, error conditions, or provide guidance on using the many optional parameters, leaving the agent reliant on the schema for anything beyond the basic creation intent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters with descriptions, so the baseline is 3. The description adds no extra meaning beyond the schema; it only restates the required status of density and diameter, which is already captured in the schema's required array.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new filament definition in Spoolman' with a specific verb and resource. It distinguishes itself from siblings like spoolman_update_filament and spoolman_create_spool by focusing on 'filament definition' and the creation aspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the verb 'create' and the resource 'filament definition,' but there is no explicit when-to-use guidance or mention of alternatives such as 'use update_filament for existing filaments.' The description lacks exclusions or context about selecting this tool over similar create tools.
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?
No annotations are provided, so the description must carry the full disclosure burden. It states 'Remove' but does not clarify that the action is permanent, what happens if the key or entity_type is invalid, or whether it affects data beyond the specified field. The description is minimal and lacks any behavioral details beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no filler. Every word contributes to the core purpose. It is appropriately concise for a simple delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two well-documented parameters and no output schema. The description successfully communicates the primary purpose, and the schema covers parameter semantics. However, it omits details about the operation's outcome (e.g., return value, success/failure behavior) and whether deletion is permanent. Given the low complexity, it is mostly complete but leaves minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes both parameters: key ('The field key to delete') and entity_type (enum with description). Since schema description coverage is 100%, the description does not need to add param details. The tool description itself offers no additional parameter semantics, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove a custom extra field from an entity type' clearly states the action (remove), the resource (custom extra field), and the scope (entity type). It distinguishes this from sibling delete tools that remove entire entities (delete_filament, delete_spool) and from upsert_field which adds/updates fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention prerequisites (e.g., field must exist) or exclusions (e.g., only for custom fields, not standard fields). The description is purely a statement of the action without contextual usage direction.
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?
With no annotations, the description discloses that the tool performs a partial update and enforces mutual exclusivity between two parameters. However, it does not mention side effects, permissions, or what happens to existing values. It provides some behavioral context but is not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences deliver essential information without fluff. Every sentence earns its place: the first defines the operation, the second clarifies parameter usage constraints. Ideal length and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 10 parameters, no output schema, and no annotations. The description covers the key update semantics and constraints, but it does not help the agent understand when to use this tool versus weight-specific siblings. The schema covers parameter definitions, so the description is adequate but leaves contextual gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaningful semantic value by explaining the partial update behavior and the mutual exclusivity of remaining_weight and used_weight, a constraint not encoded in the schema itself. This elevates the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an existing spool by ID') and identifies the resource. However, it does not distinguish this tool from sibling tools like spoolman_use_spool or spoolman_measure_spool, which also modify spool state. It is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides usage guidance ('Only provide the fields you want to change', 'remaining_weight and used_weight are mutually exclusive') but does not explain when to choose this tool over alternatives. No mention of spoolman_use_spool or spoolman_measure_spool for weight-related updates, leaving selection without guidance.
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 no annotations provided, the description must convey behavioral traits, but it only says 'Add or update' without disclosing side effects, idempotency, permissions, or what happens if the field already exists. This is a sparse treatment for a mutating operation, leaving significant uncertainty about its runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 13-word sentence that front-loads the action ('Add or update') and resource, with zero filler. It is as concise as possible while still conveying the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema, and no annotations, a one-sentence description is insufficient. It lacks guidance on success/failure behavior, reversibility, prerequisites, and how the upsert is expected to behave, making it incomplete for an AI agent to confidently invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of parameter descriptions, including semantics for key, entity_type, and field_type. The description adds the 'upsert' context but no parameter-specific details beyond what the schema already documents, so it meets the baseline of 3 without adding significant value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Add or update') and resource ('custom extra field for a given entity type'), distinguishing it from siblings like list_fields (listing) and delete_field (deletion). The verb+resource combination makes the tool's function unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for creating or modifying custom field definitions, but does not explicitly state when to use this tool over list_fields or delete_field. There are no exclusions or alternative references, leaving usage context mostly inferred from the tool name and sibling set.
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 no annotations, the description carries the full burden for behavioral disclosure. It states the destructive action but omits crucial details such as permanence, potential side effects on related entities (e.g., spools), or any requirements like existing references. This is a significant transparency gap for a delete operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no extraneous words. It is efficiently front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete tool, the description covers the basic action, but it lacks warnings about irreversibility or cascading effects on spools that reference the filament. This is especially important given the broader Spoolman context, so a more complete description would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single 'id' parameter with 100% coverage including its type and description. The tool description adds no additional semantics beyond repeating 'by ID', so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a filament by ID' uses a specific verb ('Delete') and resource ('filament'), clearly distinguishing it from sibling delete tools like delete_spool or delete_vendor. It is direct and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: the tool is for deleting a filament when you have its ID. However, it does not explicitly state when not to use it or mention alternatives, which is a moderate gap given the sibling tools.
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?
No annotations are provided, so the description carries full burden for behavioral disclosure. The description merely restates the tool's name and adds 'by its ID', providing no additional context such as read-only safety, error behavior (e.g., what happens if the ID doesn't exist), or response format. This is a significant gap for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and resource. Every word is necessary; there is zero fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no output schema), the description is minimally adequate but not complete. It lacks any mention of return value structure or failure modes. Since no output schema exists, the description should at least hint at what the response contains, but it only says 'get a single filament' which is terse. It is not genuinely helpful beyond the bare minimum.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% — the schema already fully documents the only parameter 'id' with its type, description, and exclusiveMinimum. The tool description adds nothing beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single filament by its ID' with a specific verb and resource. It distinguishes from sibling tools like list_filaments, create_filament, and delete_filament by emphasizing 'single' and the use of an ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the phrasing 'by its ID' — an agent can infer this is for retrieving one specific filament when the ID is known. However, there is no explicit guidance on when to prefer this over list_filaments or other alternatives, so it only meets the implied standard.
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 no annotations provided, the description carries the full behavioral burden, but it only says the tool checks health. It does not disclose whether the operation is read-only, what a healthy/unhealthy response looks like, or what happens if the instance is unreachable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes to explaining the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless health check tool, the description is adequate for selection, but it lacks detail about the return value or failure behavior, which is more important because no output schema is present. It is minimally complete but leaves obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters and 100% schema coverage, so the baseline is 4. There are no parameters for the description to elaborate on, and the empty schema fully defines the invocation signature.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Check' targeting the 'Spoolman instance' and its health/reachability status. This clearly distinguishes it from sibling tools like spoolman_create_spool or spoolman_get_settings, none of which address instance health.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or preconditions. The usage context is only implicit from the phrase 'healthy and reachable'; no sibling comparison is made.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the output format but does not clarify how the export is delivered (e.g., file content, download link), whether any permissions are required, or if there are side effects. This leaves significant ambiguity about the tool's runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the core function. It is front-loaded with the action and resource, and contains no filler words or unnecessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is mostly complete: it names the resource and output formats. However, it lacks specifications on how the export is returned or operational details, which is a minor gap given the absence of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the 'format' parameter with an enum and default value, and the description merely repeats these options ('JSON or CSV') without adding extra context. Since schema coverage is 100%, the description adds minimal value beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('export'), the resource ('all filaments'), and the output formats ('JSON or CSV'), which distinguishes it from sibling export tools like spoolman_export_vendors and list tools like spoolman_list_filaments. The specific verb and resource make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for exporting all filaments, but it does not explicitly say when to use this tool versus alternatives such as spoolman_list_filaments or spoolman_export_spools. There is no guidance on choosing between the export tool and list tool, nor any 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 no annotations provided, the description must carry the full burden. It merely says 'retrieve,' which is already implicit in the tool name 'get_all_settings.' It does not disclose the response format, potential size constraints, authorization requirements, or any other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear, front-loaded sentence with no unnecessary words. It efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read operation with no output schema, the description adequately states the expected result ('all Spoolman configuration settings'). However, it could be more complete by explicitly noting the contrast with spoolman_get_setting or describing the return structure, though simplicity works in its favor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There are no parameter semantics to explain, and the description does not need to add anything beyond what is already provided by the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Retrieve all Spoolman configuration settings,' specifying the verb (retrieve), the resource (Spoolman configuration settings), and the scope (all). This differentiates it from sibling tools such as spoolman_get_setting, which retrieves a single setting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It does not mention that this is for fetching all settings at once, nor does it reference spoolman_get_setting for single settings. The description only states the basic function without contextual usage recommendations.
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 no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that filament_id is required and that remaining_weight and used_weight are mutually exclusive, but these are parameter constraints, not behavioral traits. The description does not disclose return value, permissions, side effects beyond creating a spool, or error handling. The core mutation is already implied by the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main purpose, and every word earns its place. It delivers the key constraints without unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 11 parameters and no output schema, the description is quite brief. It covers the essential constraints and the schema fills parameter details, but it lacks contextual information about what a spool represents or what the response will be. It is minimally viable for invoking the tool but not fully comprehensive for an agent navigating the broader domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 11 parameters with descriptions (100% coverage), so a baseline of 3 applies. The description adds value by explicitly stating the mutual exclusivity rule between remaining_weight and used_weight and highlighting the required filament_id, which goes beyond what the schema states. However, it does not add semantics for other params.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new spool in Spoolman' with a specific verb and resource, distinguishing it from sibling create tools like create_filament and create_vendor. The added constraints about filament_id and weight parameters further clarify the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the creation counterpart to update_spool, but it does not explicitly state when to use this tool versus alternatives like update_spool or use_spool. There is no explicit when-to-use or when-not-to-use guidance beyond the basic creation purpose.
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?
No annotations are provided, so the description carries full responsibility. It states the action and format but does not disclose output structure, potential size limits, or authentication needs. The description does not contradict any 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that communicates the action, resource, and formats without any wasted words. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but since no output schema exists, the description should explain what the export returns (e.g., a file or inline content). It does not, leaving a gap in understanding the response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single 'format' parameter with an enum and description, so the baseline is 3. The description's mention of JSON/CSV adds no new information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool exports all vendors from Spoolman and supports JSON or CSV formats. The verb 'Export' and resource 'all vendors' distinguish it from sibling tools like spoolman_list_vendors and spoolman_get_vendor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when needing to export all vendors in a bulk format, but it does not explicitly state when to prefer it over alternatives like spoolman_list_vendors. No exclusionary guidance is given.
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?
No annotations are provided, so the description carries the burden. The verb 'Get' clearly indicates a read-only operation, but it does not disclose error behavior, return format, or any edge cases. This is acceptable but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no redundant words, perfectly sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is functionally sufficient but lacks details about the return value or potential errors. More context would improve completeness for an agent unfamiliar with the domain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'id' parameter described as 'The vendor ID'. The description reinforces this by saying 'by its ID', but adds no additional meaning beyond what the schema already provides, which aligns with the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a single vendor by ID, using specific verb 'Get' and resource 'vendor'. This distinguishes it from sibling tools like list_vendors, which retrieves multiple vendors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you have a specific ID, but it does not explicitly mention when to use it instead of list_vendors or other vendor-related tools. No alternatives or exclusions are 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?
No annotations are provided, so the description carries the burden. It states the tool lists 'all' lot/batch numbers from 'currently tracked' spools, implying a read-only scoped query. However, it does not disclose return format, pagination, or any side effects, which would be useful for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource. Every word is meaningful, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should clarify the return shape. It says 'list all lot/batch numbers' but does not specify whether the result is unique values, includes spool identifiers, or is sorted. This is a minor gap for a simple list tool, but the description is otherwise adequate for a zero-parameter operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, so the description does not need to explain parameter semantics. The baseline for zero-parameter tools is 4, and the description does not need to add anything beyond the schema, which is empty.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists lot/batch numbers of spools, using a specific verb and resource. This distinguishes it from sibling list tools like list_spools or list_filaments, which target different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, such as list_spools or list_filaments. The description does not mention exclusions, prerequisites, or context where this tool is preferred, leaving the agent to infer usage.
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?
With no annotations, the description conveys that this is a read-only listing operation ('List') and scopes it to all existing material types. However, it does not disclose return format, pagination, or whether custom material types are included, leaving some behavioral uncertainty.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately states the action and resource, followed by clarifying examples. There is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter list tool, the description states the core purpose. However, without an output schema, it does not specify whether the response is a list of strings, objects, or IDs, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the description is not expected to add parameter-level details. The schema coverage is trivially complete, and the baseline for no-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action 'List' and the resource 'filament material types' with concrete examples (PLA, PETG, ABS). This distinguishes it from sibling tools like spoolman_list_filaments by focusing on material types rather than filament records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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 spoolman_list_filaments or spoolman_list_vendors. The description implies it is for retrieving material types but does not state explicit use cases 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?
No annotations are provided, so the description carries the full burden for behavioral disclosure. It mentions listing/searching and filter options, but omits pagination behavior, default sort, archived-spool handling (beyond the schema's allow_archived hint), and response format. This is a notable gap for a list tool with 11 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant information. It states the action and key filterable facets, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 optional parameters and no output schema, the tool is moderately complex. The schema covers parameter semantics, but the description lacks return-value context, pagination defaults, and suppression of archived spools, making it minimally viable rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds a high-level grouping of filterable fields ('filament, vendor, material, location, lot number') but does not add syntax or format details beyond the schema, which already documents each parameter individually.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List and search' with the resource 'spools in Spoolman', and enumerates filter dimensions (filament, vendor, material, location, lot number), making it clearly distinguishable from sibling tools like spoolman_get_spool (singular retrieval) or spoolman_create_spool (creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing/searching spools with filters, which is clear context. However, it does not explicitly contrast with spoolman_get_spool for single-spool retrieval or state when not to use this tool, so it stops short of a 5.
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?
With no annotations, the description must carry the burden of behavioral disclosure. It clearly states the action (logging consumption) and the mutual exclusivity of the two usage parameters, but does not explain side effects (e.g., how the spool's remaining material is updated, whether consumption accumulates, or if authorization is required). This leaves some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the core action front-loaded and zero filler. Every word earns its place, including the critical constraint about parameter exclusivity. It is an exemplar of concise, structured tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (3 parameters, no output schema, no nested objects), so the description largely suffices. However, as a mutation tool without annotations, it lacks context about what happens to the spool after consumption is logged. The absence of alternatives or exclusions also leaves some completeness gaps, making it adequate but not exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides complete descriptions for all three parameters (100% coverage), so baseline is 3. The description adds meaningful semantics by explicitly stating the rule 'Provide either use_length or use_weight, not both', which is not captured in the schema's individual parameter descriptions or required fields. This enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Log') and resource ('filament consumption for a spool'), making its purpose unambiguous. This sufficiently distinguishes it from sibling tools like 'spoolman_measure_spool' (which measures rather than logs) and 'spoolman_update_spool' (which edits spool settings).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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, such as distinguishing it from measuring or updating spools. The only usage hint is the constraint about providing either use_length or use_weight, which is more of a parameter rule than a 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?
With no annotations, the description carries the full burden. It discloses that the tool returns remaining weight and usage stats, which is useful, but it does not mention error behavior (e.g., unknown ID) or any access prerequisites. The simple read nature is adequately conveyed, but some transparency gaps remain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that clearly states the operation and key output details without any wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the primary return content ('remaining weight and usage stats') and the tool is simple with one parameter. However, no output schema exists, and the description does not specify response structure or error cases, leaving minor gaps given the lack of structured return documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for the single parameter 'id' is 'The spool ID' with an exclusiveMinimum, providing 100% coverage. The tool description adds no extra semantic meaning beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' with the resource 'a single spool by its ID', clearly distinguishing it from list operations like list_spools. Mentioning 'remaining weight and usage stats' further clarifies what data is returned, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a spool ID is known and a single spool's details are needed. However, it does not explicitly state when to prefer this over alternatives like list_spools or provide exclusion criteria, so guidance is only 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?
With no annotations, the description carries the burden of behavioral disclosure. It explains filtering support but does not explicitly state that the operation is read-only or describe pagination behavior (e.g., limit/offset semantics). The 'and more' is vague, leaving some behaviors undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. The second clause is slightly vague ('and more') but not wasteful. It could be more precise, but it remains efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a 10-parameter tool with no output schema, the description is minimal. It does not explain default behavior (e.g., returns all filaments if no filters) or confirm that results are paginated, though limit/offset parameters imply it. This leaves some gaps for a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all 10 parameters with descriptions (100% coverage), so the baseline is 3. The description's mention of filters (vendor, material, color, article number) adds no meaning beyond what the schema provides, and 'and more' adds no specific value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List and search') and the resource ('filaments in Spoolman'), distinguishing it from sibling tools like list_spools and list_vendors. It also mentions filtering capabilities, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: listing/searching filaments. However, it does not explicitly exclude alternatives (e.g., get_filament for a single filament) or mention when not to use it, so it falls short of a 5.
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?
With no annotations provided, the description carries the full burden. It indicates a read-only operation ('List and search') and mentions pagination behavior, but does not explicitly state that it does not modify data, nor does it disclose any authentication requirements, rate limits, or response format. The description adds some behavioral context but is not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary purpose and immediately followed by relevant capabilities. There is no redundant information or filler, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of a list/search tool and a fully self-describing schema, the description covers the essential functionality (filtering, pagination). It does not mention the return shape, but for a simple list tool with no output schema, this is not a critical gap. The absence of annotations and output schema is partially compensated by the clear schema and the nature of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage with clear descriptions for all four parameters (name, sort, limit, offset). The description summarizes filtering by name and pagination, which adds marginal value but does not go beyond what the schema already says. According to the baseline rule, this scores a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('List and search vendors') and the resource (vendors in Spoolman). It is distinct from sibling tools like spoolman_get_vendor (single vendor) and spoolman_list_filaments (different resource). The verb and object are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used for listing/searching vendors and mentions filtering and pagination, which gives some context. However, it does not explicitly state when to prefer this over spoolman_get_vendor or provide alternatives/exclusions. The guidance is implied rather than explicit, so it falls short of a clear when-to-use directive.
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?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the action 'List' and gives no details about the return format, uniqueness of article numbers, pagination, or absence of side effects. The agent cannot anticipate whether results are deduplicated or how they are structured.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant information. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 params) and lack of output schema, the description is mostly adequate. However, it leaves ambiguity about whether the list contains duplicates or unique article numbers and does not mention the exact return type (e.g., array of strings). This prevents it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema is trivially fully covered. The baseline for 0 parameters is 4, and the description adds a clear scope ('all article numbers of filaments'), which adds slight semantic value beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the verb 'List' and the resource 'article numbers of filaments', distinguishing it from sibling tools like list_filaments. The scope 'currently tracked in Spoolman' adds precise context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving article numbers, which differentiates it from alternatives like list_filaments or list_lot_numbers. However, it does not explicitly state when not to use it or mention 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?
With no annotations, the description carries the burden of behavioral disclosure. It indicates a read-only 'list' operation with no side effects, but does not disclose details such as pagination, ordering, or return format. The behavior is simple, so the minimal disclosure is acceptable but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the tool's purpose. There is no wasted wording or unnecessary detail, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, parameter-free list tool, the description fully captures what the tool does. Without an output schema, a brief mention of the result being a list of locations is sufficient—no further context is required for effective selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100% (empty schema). The description adds no parameter details because there are none, and the baseline for zero-parameter tools is 4. No additional semantics are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all spool storage locations defined in Spoolman. The verb 'List' and the specific resource 'spool storage locations' distinguish it from sibling list tools like list_vendors and list_filaments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does 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. It simply states the action without mentioning any use case, prerequisites, or exclusions, leaving the agent to infer applicability.
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?
With no annotations, the description must convey behavioral traits. It clarifies the input unit (grams) and that the weight includes the spool, but it does not disclose that the calculation likely depends on the spool's empty weight or any side effects. This is a moderate gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly states the action and input. There is no wasted wording, making it highly concise and structurally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool, the description provides adequate information to understand the core operation. However, it lacks details about prerequisites (like knowing the spool's empty weight) and potential effects, so it is not fully complete given the absence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for both parameters (id and weight), achieving 100% coverage. The description only repeats the weight unit and spool+filament concept without adding new meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a spool's remaining filament using a weight measurement, with the specific scope of 'spool + filament together in grams.' It distinguishes itself from sibling tools like spoolman_update_spool by focusing on measurement-based updates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: to update remaining filament when a physical weight measurement is available. It offers clear context but does not explicitly mention alternatives or when not to use this tool, falling short of the 'explicit when/when-not' bar.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description is minimal and does not state whether the export returns data directly, creates a file, or has any side effects. It also doesn't mention safety aspects (e.g., read-only nature), auth requirements, or behavior for large datasets. However, 'export' implies a read operation and the description is not misleading, adding some value but lacking richer 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Export all spools from Spoolman as JSON or CSV.' It contains no redundant words and directly conveys the tool's purpose and output format options. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter with a schema, no output schema, and no annotations. The description combined with the schema is fairly complete for this complexity level. It covers the action, resource, and format. It could mention what the response looks like or any edge cases, but for a basic export tool, the current level is adequate and nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage of the single 'format' parameter, including an enum ('json', 'csv') and a default value. The description adds no extra meaning beyond what the schema already states ('Export format: 'json' (default) or 'csv''). With high schema coverage, the baseline is 3, and the description does not go beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Export all spools from Spoolman as JSON or CSV.' It uses the specific verb 'export', identifies the resource ('all spools'), and specifies the output formats. This distinguishes it from sibling export tools like spoolman_export_vendors and spoolman_export_filaments, as well as from list/get spool operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: to export all spools in JSON or CSV format. It does not explicitly mention alternatives or exclusions, such as using list_spools for in-app viewing or get_spool for a single spool, but the purpose is unambiguous given the name and description. This is clear context without explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that the tool is a read operation ('Get') and specifies what information is returned, which is basic transparency. However, it does not explicitly address safety (e.g., whether it is non-destructive), authentication requirements, or side effects, though 'Get' implies read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main action and resource, followed by specific details in parentheses. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description adequately covers the purpose and return content by listing the information fields. It could be more explicit about response format or potential errors, but for a low-complexity info endpoint this is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema coverage is 100% (empty schema), so there is nothing to document. The baseline for 0 params is 4, and the description does not need to add parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('general Spoolman API information'), and lists specific data points (version, database type, debug mode, paths). This distinguishes it from sibling tools that focus on vendors, filaments, spools, or settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a utility for retrieving API-level details, which is appropriate when the agent needs system information rather than entity data. However, it does not explicitly state when to prefer this over other tools or mention any alternatives or 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?
With no annotations, the description carries the transparency burden. It implies a read-only listing via 'List all' and clarifies the scope to 'custom extra fields', but does not disclose return format, ordering, pagination, or whether built-in fields are excluded. Sufficient for a simple read operation but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource, avoiding any redundant or filler content. It effectively communicates the essential information in minimal space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter list tool without an output schema, the description adequately defines what is listed and the entity-type parameter. It could optionally mention the return format or behavior, but given the tool's simplicity, the description is sufficiently complete for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single parameter, including an enum and explicit descriptions for each value. The description's parenthetical '(vendor, filament, or spool)' simply restates the enum, adding no new meaning beyond the schema. Baseline 3 is appropriate given complete schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('all custom extra fields'), and the scope ('for a given entity type'). It distinguishes this tool from sibling list tools (e.g., list_vendors, list_filaments) by focusing on extra fields rather than the entities themselves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the required context—given an entity type—which serves as a usage constraint. It does not explicitly mention when not to use it or contrast with alternatives, but the entity-type limitation gives clear guidance for correct invocation.
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?
With no annotations, the description must disclose side effects. It does state that the tool triggers a backup (a side effect) and returns the backup file path. However, it does not mention potential effects like whether it overwrites existing backups, whether it blocks, or any permission requirements. This is a moderate level of disclosure for a simple trigger.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences that front-load the core action and include the return value. Every word earns its place, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description sufficiently covers its behavior and return value. The 'SQLite only' constraint is a valuable addition. No further details are needed for an agent to invoke this tool correctly in most scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description accurately adds no parameter-specific meaning since there are none. Baseline for 0 parameters is 4, and the 'SQLite only' qualifier provides useful context beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (trigger a database backup), the resource (the Spoolman instance), and a key qualifying constraint (SQLite only). It is specific and distinguishes itself from all sibling tools, none of which are backup-related.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool should be used when a database backup is needed, but it does not explicitly state when to use it over alternatives or when not to use it. Since there are no sibling backup tools, the usage context is clear but not formally stated.
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?
With no annotations provided, the description takes on the responsibility of disclosing side effects. It explicitly warns that deletion cascades to associated filaments, which is a critical behavioral trait for a destructive operation. It does not mention irreversibility or permissions, but the cascade disclosure goes beyond a plain 'delete' statement and covers the most important consequence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no wasted words. It front-loads the action ('Delete a vendor by ID') and then adds the essential cascading detail. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter delete operation with no output schema and no annotations, the description covers the action and the key side effect (cascade). It could potentially mention that the operation is permanent or irreversible, but 'delete' already implies that. Given the tool's simplicity, the description is sufficiently complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the only parameter (`id` with type, description, and minimum). Schema description coverage is 100%, so the description does not need to add parameter-level detail. The description adds no additional meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') with a specific resource ('vendor by ID') and clearly states the scope via the cascade note. It distinguishes itself from sibling tools like spoolman_delete_filament and spoolman_delete_spool by targeting vendors specifically. The action and resource are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is for removing vendors, and the mention of cascading to associated filaments sets expectations about the tool's broader impact. While it doesn't explicitly name alternatives like spoolman_update_vendor or spoolman_delete_filament, the purpose is evident from the tool name and description, providing clear context without listing exclusions.
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?
With no annotations provided, the description carries the burden of behavioral disclosure. It goes beyond a bare rename by stating 'All spools at the old location will be updated to the new name,' revealing an important side effect. However, it does not disclose error conditions or return value, so it is slightly incomplete for full 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/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the core purpose and followed by a critical side effect. Every word earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two required params, no nested objects, no output schema), the description adequately covers purpose and a key behavioral consequence. It does not mention return values or error handling, but for a rename operation with well-documented parameters, the information is sufficient for an AI to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, so the description need not add parameter information. The description does not go beyond the schema—it simply restates 'old location' and 'new name' without adding syntax or behavioral specifics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-object pair, 'Rename an existing spool storage location,' which clearly identifies the tool's action and resource. It distinguishes this tool from siblings like spoolman_list_locations or spoolman_delete_spool by focusing on renaming, and the follow-up sentence reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool to rename an existing spool location. It implies the appropriate time to invoke the tool, though it does not explicitly mention alternatives or when not to use it. Since no conflicting sibling performs a rename, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the key behavior of partial updates (fields not provided remain unchanged). However, with no annotations, it does not address error handling, required permissions, or response format, leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core purpose and a critical usage rule. There is no wasted verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description is brief, it covers the essential update semantics, and the schema fully documents all parameters. The lack of an output schema means return values aren't described, but this is a minor gap for a straightforward update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides full descriptions for all 14 parameters (100% coverage). The description adds valuable semantic guidance beyond the schema by clarifying that only the fields to change should be provided, which is essential for correct invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Update an existing filament by ID.' It specifies the resource (filament), the operation (update), and the identifier (ID), distinguishing it from sibling tools like create or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Only provide the fields you want to change' provides clear guidance on partial update semantics. It implies usage context for modifying an existing filament without specifying exclusions or alternatives, but the context is unambiguous.
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?
No annotations are provided, so the description carries the burden. It discloses that this is an update operation and that only provided fields are changed, but it does not mention error handling, return values, or conditions like vendor existence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action, with an additional useful guideline. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with full schema coverage, the description is mostly sufficient. It lacks return value or error behavior, but the core semantics are clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions, but the description adds the partial-update behavior, clarifying that omitted fields are not changed. This is beyond the schema's 'New name'/'New comment' labels.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates an existing vendor by ID, using a specific verb and resource. It distinguishes from siblings like create_vendor, delete_vendor, and get_vendor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies usage when an existing vendor needs modification by ID. The instruction 'Only provide the fields you want to change' provides context for partial updates, but it does not explicitly mention when not to use it or alternative tools.
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:

[![spoolman-mcp MCP server](https://glama.ai/mcp/servers/Disane87/spoolman-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Disane87/spoolman-mcp)

Score Badge

Copy to your README.md:

[![spoolman-mcp MCP server](https://glama.ai/mcp/servers/Disane87/spoolman-mcp/badges/score.svg)](https://glama.ai/mcp/servers/Disane87/spoolman-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/Disane87/spoolman-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server