swsd-mcp

Server Quality Checklist

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

Latest release: v2.2.0
Disambiguation4/5
Most tools have distinct purposes, but there is some overlap between swsd_list_incidents and swsd_list_my_incidents, and between swsd_assign_incident and swsd_update_incident. The descriptions help clarify, so only minor ambiguity.
Naming Consistency5/5
All tools follow the swsd_verb_noun pattern consistently, e.g., swsd_create_incident, swsd_list_incidents, swsd_get_incident. No mixing of styles.
Tool Count4/5
33 tools is on the higher side but justified by the breadth of SWSD features covered (incidents, problems, solutions, catalog, users, etc.). A few tools like swsd_get_me and swsd_health_check are thin but acceptable.
Completeness3/5
Core workflows for incidents, problems, and service requests are covered, but notable gaps exist: no delete tools for any resource, no update for problems or solutions, and no create for solutions. This limits full lifecycle management.
Average 4.5/5 across 33 of 33 tools scored.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 49 commits in the last 12 weeks
- Last stable release on August 10, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.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

Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by stating it is a WRITE operation that honors SWSD_WRITE_MODE and does not retry on transient failure. Annotations only indicate readOnlyHint=false, so these additional behavioral details help the agent understand failure handling and configuration dependence.
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 extremely concise: two sentences with no wasted words. The first sentence clearly states the purpose and resource, and the second summarizes required parameters and key behaviors. It is front-loaded and 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 that the tool has 4 parameters (all required), a simple schema, and no output schema, the description adequately covers the action. However, it lacks details on success/failure outcomes, authentication requirements, or any side effects. The mention of 'no retry' partially addresses failure behavior, but overall completeness is moderate.
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?
Although schema description coverage is 100%, the tool description merely lists the required parameter names without adding new semantic meaning. It restates that minutes_parsed corresponds to a SWSD field, but this is already in the schema. Thus, it adds minimal value 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 verb 'Log time' and the resource 'SWSD incident, problem, change, or release', specifying the exact object types. It lists required parameters, making the action unambiguous. This differentiates it from sibling tools like swsd_list_time_tracks or swsd_update_time_track.
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. There is no mention of prerequisites, such as needing an existing record, or when not to use it. The mention of SWSD_WRITE_MODE gives minimal context but no explicit comparison to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-idempotent behavior. Description adds context about transport constraints and the SWSD_WRITE_MODE setting, but does not disclose potential side effects (e.g., overwriting existing attachments, file size limits, permission requirements).
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?
Description is two concise sentences, front-loaded with purpose, followed by parameter guidance and behavioral note. No wasted words or redundant information.
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 complexity (5 parameters, 3 required, no output schema), the description covers purpose and transport constraints but is missing crucial details: return format, error conditions, idempotency implications (already in annotations), and prerequisites like parent record existence. Adequate but not 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?
Input schema covers all 5 parameters with 100% description coverage. The description adds value beyond schema by guiding which parameter to use (content_base64 for HTTP, file_path for stdio), and by noting the write mode. This extra context justifies a score above baseline 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?
Description uses specific verb 'Upload' and clearly specifies the resource as attachment to various SWSD parent types (incident, problem, change, etc.). It differentiates from sibling tools like swsd_add_incident_comment (comment vs attachment) and swsd_create_incident (creation vs attachment).
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 provides limited usage guidance: it tells when to use content_base64 vs file_path based on transport (hosted/HTTP vs stdio), and mentions WRITE mode. However, it lacks explicit when-to-use vs alternatives, prerequisites (e.g., parent record must exist), 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?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that it returns specific fields and a use case, but does not further detail behavioral traits (e.g., pagination, query behavior). The description is consistent with 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 two sentences, front-loading the action ('List SWSD roles'), and includes essential information without any waste. Every sentence adds value.
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 list tool, the description covers purpose, return fields, and a use case. The existence of an output schema (not shown) likely covers output structure. Could be slightly more explicit about list nature, but overall 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 all parameters (page, per_page, query) are already documented with descriptions, defaults, and constraints. The description does not add parameter-specific information, which is acceptable given the schema completeness.
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 SWSD roles, provides a parenthetical clarification ('permission profiles'), and specifies the returned fields (id, name, description). No sibling tool lists roles, so it is well-differentiated.
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 gives a concrete use case ('understanding what users can do when triaging permission-related tickets'). It implicitly indicates when to use this tool, though it does not explicitly mention when not to use it or list alternatives; however, no alternative exists among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, openWorldHint=true, so the safety profile is clear. The description adds value by detailing the structure of audit entries and mentioning the cost advantage over the alternate tool. No contradictions with annotations.
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 five sentences, front-loading the main purpose and then adding details. It is concise with no unnecessary words, but could be slightly more structured with bullet points for the audit entry fields.
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 presence of an output schema (not shown) and full input schema descriptions, the description covers purpose, usage guidance, parameter hints, and cost comparison. It doesn't discuss error handling or rate limits, but the annotations cover idempotency and open-world behavior. Overall adequate for the tool's complexity.
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 is 100%, and the description adds minimal extra meaning beyond the schema: it mentions the object_type list in prose and adds a note about per_page default being sufficient for recent activity. However, the id parameter explanation is already in the schema description, so added value is marginal. 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 the tool lists audit logs for SWSD records, specifies the content of each entry (action, message, user, timestamp), and distinguishes from sibling tool swsd_get_incident by noting it's cheaper for audit-only needs.
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 context for when to use ('who changed this ticket?', 'what happened since I last looked?') and explicitly mentions that it's cheaper than swsd_get_incident with detail_level=long for audit history, offering guidance on choosing between tools. However, it doesn't specify when not to use the tool or prerequisites like record existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the description does not need to cover safety. It adds that results are paginated via 'page' and 'per_page' parameters, and lists return fields. No contradictions, but no additional behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no extraneous information. It front-loads the purpose and efficiently references the sibling tool, making it easy for an AI 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?
Given the tool is a straightforward list operation with pagination, the description covers all necessary aspects: purpose, return fields, and related tool. An output schema exists, so return structure is further clarified. No gaps for agent invocation.
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 has 100% description coverage, so parameters are already well-documented. The description does not add significant new meaning beyond the schema, thus 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 the verb 'List' on resource 'comments on a SWSD incident' and lists the returned fields. It distinguishes from sibling tool 'swsd_add_incident_comment' by mentioning it's for adding, not listing.
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 explicitly directs to use 'swsd_add_incident_comment' for adding comments, providing clear alternative guidance. However, it does not address when to choose this tool over other list tools, but given the explicit sibling reference, it is adequate.
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?
Adds 'WRITE — does not retry on transient failure' beyond annotations (readOnlyHint false, idempotentHint false). This provides useful error-handling context. Still lacks details on auth or side effects for openWorldHint true.
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 clear sentences plus a tagline. No filler, front-loaded with action. Efficient 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?
Covers purpose, parameters, and return value. Missing discussion of side effects (openWorldHint true) or idempotency implications. Adequate for a creation tool with good annotations.
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 100% of parameters with descriptions. Description repeats required/optional info and adds that the created task is returned, which is not in the schema. Baseline 3, plus slight value from return info.
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?
Starts with 'Create a new sub-task on a SWSD incident', clearly stating verb and resource. Distinguishes from sibling tools like swsd_list_incident_tasks or swsd_update_task_state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Lists required and optional parameters, aiding usage, but does not explicitly state when to use this tool versus alternatives (e.g., swsd_create_incident). No 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by specifying the return fields (id, name, description) and hints at its usage, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are concise and front-loaded. First sentence states the purpose and return values, second sentence provides usage guidance. No wasted 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?
Given the presence of output schema and annotations, the description provides necessary context: purpose, return structure, and usage. It could mention pagination but parameters already cover that.
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 clear descriptions for page, per_page, and query. The description does not add parameter details, so it meets the baseline for high-coverage schemas.
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 'List' and resource 'departments', clearly stating what it does and returns (id, name, description). It differentiates from sibling list tools by focusing on departments and providing a usage context for validating department_name.
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?
Explicitly states when to use it: 'Use this to validate department_name before incident write tools.' Provides clear context without needing exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false), non-idempotent, and open world. The description adds value by disclosing that the tool honors SWSD_WRITE_MODE and does not retry on transient failures, which is critical behavior not captured in annotations. No contradiction.
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 tightly written sentences. First sentence states purpose and scope; second adds behavioral notes. No redundant words. Front-loaded and 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?
The description covers purpose, input, and behavioral nuance (write mode, no retry). No output schema is provided, but the tool's return behavior is not critical for selection. It could specify success response, but completeness is adequate for a write tool with good schema coverage.
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 is 100%, so baseline 3. The description mentions 'Pass name and/or minutes_parsed' but adds no semantic detail beyond the schema descriptions. It does not compensate with additional parameter context, so score remains at 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 verb (update), resource (existing SWSD time entry), and scope (on incident, problem, change, or release). It distinguishes from siblings like swsd_log_time (create) and swsd_list_time_tracks (list). The purpose is 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 implies this is for updating existing time entries, contrasting with a creation tool. It mentions behavioral traits (WRITE mode, no retry) but does not explicitly state when to use vs alternatives. Still, context is clear enough for an agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds value by listing returned fields (id, name, description, disabled, member_count) and does not contradict 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?
Two-sentence description is concise, front-loaded with the purpose, and includes only essential information without redundancy.
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 presence of an output schema and annotations, the description adequately covers the tool's purpose, return fields, and usage context, leaving no critical 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?
Schema description coverage is 100%, so the description adds no additional parameter meaning beyond the schema. 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 the action 'List SWSD groups' and identifies the resource as 'assignment teams', distinguishing it from sibling list tools like list_incidents or list_users.
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 provides context ('useful for understanding team structure when triaging tickets') but does not explicitly exclude alternative tools or specify when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, idempotentHint, openWorldHint; description adds that it returns specific fields and validates site_name. No contradiction, but does not detail pagination 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?
Two sentences, front-loaded with purpose, no wasted words.
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?
With good annotations, output schema, and clear parameters, the description is sufficient for understanding the tool's behavior and use case.
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 is 100% with descriptions for page, per_page, and query. The tool description adds minimal extra meaning beyond validating site_name.
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?
Clearly states it lists SWSD sites (physical locations) and returns specific fields. Distinguishes from sibling tools by emphasizing validation use.
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?
Provides explicit guidance to use this tool for validating site_name before incident write tools. Could benefit from mentioning when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. Description adds usage context (object types and workflow placement) without contradicting annotations. No behavioral surprises.
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 sentences: first states the action, second gives usage guidance. Front-loaded with purpose, no unnecessary words. Efficient and clear.
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 purpose (listing time entries) and that an output schema exists, the description sufficiently covers what the tool does, when to use it, and what object types it supports. No missing critical information for a read-only list 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?
Schema coverage is 100% so the schema already documents all parameters. Description mentions object types (matching enum) but adds no additional semantic detail beyond that. 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 it lists time entries for specific SWSD object types (incident, problem, change, release). It distinguishes itself from siblings like swsd_log_time and swsd_update_time_track by mentioning 'before adding/updating time'.
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?
Explicitly says 'Use this before adding/updating time when you need existing work-log context', providing clear context. While it doesn't explicitly name alternatives or state when not to use, the usage scenario is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that it returns specific fields and parameter effects, but does not add substantial behavioral insight beyond what annotations and schema provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences. First states purpose and returns, second and third give usage for key parameters. No redundant information, well front-loaded.
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?
With output schema present and schema covering all parameters, the description adds essential usage guidance. It covers the tool's purpose, key parameter uses, and connection to sibling tools, making it complete for an AI agent.
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%, baseline 3. Description adds context for two parameters: 'available_for_assignment_only' ties to sibling tool, and 'email' specifies exact lookup. This adds meaningful guidance beyond 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 'List SWSD users' and lists the returned fields. It distinguishes itself from siblings by mentioning specific parameter uses for assign_incident and exact lookup, providing differentiation.
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?
Provides explicit guidance: use 'available_for_assignment_only: true' to find valid assignees for swsd_assign_incident, and 'email' to look up one user exactly. This connects to sibling tools, though it doesn't explicitly say when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds 'WRITE — does not retry on transient failure' which provides failure behavior beyond annotations (readOnlyHint=false, idempotentHint=false). It also notes the limitation on changing is_private, which is a behavioral constraint not evident from 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 compact (4 sentences) and front-loaded: first sentence states purpose, second lists parameters, third adds a limitation, fourth is a concise behavioral flag. No redundant information.
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 description covers the action well but does not mention return value or error handling. Given no output schema, the agent might need to infer outcomes. However, for a simple update tool, this may be adequate.
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 value by explaining that incident_id accepts both internal id and human-facing number with auto-detection, which is not in the schema. It also clarifies that body replaces existing text.
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 'Update the body of an existing SWSD incident comment,' specifying the verb (update), resource (incident comment), and scope (body). It distinguishes from sibling tools like swsd_add_incident_comment which adds new comments.
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 explicitly lists required parameters (incident_id, comment_id, body) and provides a key caveat: the is_private flag cannot be changed. This implies when to use and when to avoid. It doesn't explicitly contrast with alternatives but the sibling list provides context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate write, non-destructive, non-idempotent, open-world. The description adds critical context: does not retry on transient failure, suggests verifying with `swsd_get_incident`, and notes the returned incident ID. No contradiction.
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?
Well-structured with front-loaded purpose. Each sentence adds value, but slightly verbose. Could be trimmed without losing information, but still clear and organized.
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 complexity (5 params, nested objects, write operation), the description covers purpose, prerequisites, parameter details, return value, retry guidance, and validation. No output schema provided but description mentions returned ID. Adequate for agent to use correctly.
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% (baseline 3). Description adds workflow context: `catalog_item_id` auto-populates incident fields, `request_variables` requires `custom_field_id` from variables, `custom_fields` requires pre-discovery. Also specifies validated types (Text, Dropdown, Number, Checkbox, Date).
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 submits a SWSD catalog request to create an incident with `is_service_request: true`. It differentiates from siblings like `swsd_create_incident` by specifying the catalog context and auto-set flag.
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?
Provides explicit guidance: use `swsd_list_catalog_items` and `swsd_get_catalog_item` to find and inspect catalog items, and `swsd_describe_custom_fields` for custom fields. Lacks direct comparison to alternatives but implies when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds that it returns active fields by default, how to see retired ones, hints that the tenant may have 100+ fields (justifying pagination), and includes a note about write operations being supported in other tools. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and returns info. It then adds filtering guidance and a v2 note about writes. While the v2 note is slightly tangential, it is relevant for integration context and does not bloat the description too much.
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?
The description fully covers the tool's behavior: what it returns, how to filter, pagination implications, and even unsupported field types for writes in related tools. With an output schema present, the description completes the picture for an agent.
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?
With 100% schema coverage, the description adds extra meaning: it explains the purpose of scope/module filtering and the default for active_only. It also hints at pagination due to large tenant. The v2 note, while mostly about other tools, provides context for the custom_fields parameter used elsewhere.
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 the custom-field schema and enumerates the fields returned (id, name, type, required, scope, module, values, help_text). This differentiates it from all sibling tools, which focus on incidents, solutions, catalogs, etc.
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 explains when to use this tool (understanding tenant config, documenting integrations) and provides filtering advice (scope, module, active_only). It does not explicitly state when not to use it or name alternatives, but the context is sufficient for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and open-world hints. Description adds context about catalog items' nature and relation to other operations, strengthening behavioral understanding beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: purpose, definition, workflow. Every sentence serves a purpose, front-loaded, no superfluous content.
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?
With output schema present, description need not detail returns. Covers tool purpose and integration with sibling tools. Lacks explicit mention of pagination behavior, but schema parameters hint at it.
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% with detailed descriptions. Description adds value by explaining the broader purpose of catalog items, helping interpret filters, but does not add specific parameter info beyond 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 lists catalog items, specifies what catalog items are (service request templates), and names sibling tools for further actions.
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?
Provides explicit workflow guidance: list items, then use swsd_get_catalog_item for details, then swsd_create_service_request to submit. Does not explicitly mention when to avoid this tool, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutation and non-idempotence. Description adds that it does not retry on transient failure and that state names are tenant-specific. Offers context beyond structured fields.
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?
Every sentence adds value: purpose, safety comparison, state examples, usage tip, failure behavior. No fluff, well front-loaded.
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 specific function and sibling tools, the description is nearly complete. Covers prerequisites, failure behavior, and tenant-specific states. Could mention reversibility but not critical.
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 both parameters, but description enriches: explains id auto-detection between internal and human-facing numbers, lists common state values, and advises checking current state.
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?
Clearly states the action: transitions an SWSD incident to a new state, with examples. Distinguishes from sibling swsd_update_incident as a safer wrapper, narrowing agent decision surface.
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?
Provides explicit guidance to call swsd_get_incident first to see the current state. Notes it's a WRITE operation and does not retry on failure. Could be more explicit about when to prefer this over swsd_assign_incident, but sufficient.
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?
Description adds 'WRITE — does not retry on transient failure' beyond the annotations (readOnlyHint=false, idempotentHint=false), providing crucial retry guidance. No contradiction with annotations; it complements them effectively.
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?
Three sentences, each purposeful: states action, differentiates from sibling, gives usage tip, and flags failure behavior. No redundancy, front-loaded with key information.
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 two-parameter write tool without output schema, the description covers purpose, usage, prerequisites, and failure behavior comprehensively. No gaps remain.
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 has 100% parameter coverage, but description adds context: the id field auto-detects internal vs. human-facing numbers, and assignee_email must be a valid available agent. This goes beyond raw schema definitions.
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 ('Assign an SWSD incident to an agent by email') and distinguishes it as a 'Safer wrapper around swsd_update_incident' that narrows the decision surface to assignment only, differentiating it from sibling tools like swsd_update_incident.
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?
Explicitly recommends using swsd_list_users first to find valid assignees and warns about transient failures. It implies when to use (for assignment) versus alternatives (use swsd_update_incident for broader updates), though it doesn't list explicit when-not-to-use conditions.
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?
Adds details about variables structure (id, name, kind, options) and that the full item is passed through, supplementing readOnlyHint and idempotentHint annotations without contradiction.
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?
Four sentences, front-loaded with main purpose, no unnecessary words.
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 output schema exists and annotations cover safety, the description explains the return value (variables structure) and note about full item, making it complete for a single-get 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?
Schema already describes 'id' parameter; description adds that it comes from swsd_list_catalog_items, providing source context.
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?
Clearly states it gets a single catalog item by ID, including variables. Distinguishes from list_catalog_items (lists) and siblings like get_incident (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implicitly guides to use this to obtain variables for creating service requests, but lacks explicit when-not-to-use or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, indicating safe read operations. The description adds that 'Categories form a hierarchy (parent_id links)', which is useful behavioral context beyond annotations. No contradiction detected.
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; the first states purpose and return fields, the second provides usage guidance. No fluff, every sentence earns its place.
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 presence of an output schema (context indicates 'Has output schema: true'), the description does not need to explain return values in depth. It sufficiently covers the essential return fields and usage context, making the tool complete for an agent.
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 description coverage is 100%, so the schema fully documents the three parameters (page, per_page, query). The description adds value by mentioning the return includes immediate children and default_assignee_id, providing context for how parameters might affect results, though it does not detail parameter syntax.
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 explicitly states 'List SWSD incident/solution categories' and lists the returned fields (id, name, parent_id, immediate children, default_assignee_id). It clearly distinguishes itself from sibling tools by focusing on categories, not incidents or other entities.
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 advises to 'Use this to validate category_name before swsd_create_incident or swsd_update_incident', providing clear context for when to use the tool. It does not explicitly state when not to use it, but the specific guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint: true. The description adds value beyond annotations by clarifying the compact summary return format and the OR-ed filter semantics. It does not contradict 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?
Two sentences, front-loaded with purpose and key details. No unnecessary words. Every sentence earns its place.
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 complexity (8 parameters, output schema exists), the description is complete. It explains the compact return format, filter semantics, and typical use case. The output schema handles return details, so no need for further elaboration.
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% with each parameter having a description. The description adds meaning beyond the schema by explaining that filters use SWSD repeated-key array semantics (OR-ed within a filter). Baseline 3, elevated due to extra context.
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 it lists SWSD problems with structured filters and pagination, specifies returned fields (id, name, state, etc.), and distinguishes from swsd_get_problem (full detail). Also explains use case: investigating recurring incidents or root causes. This is a specific verb+resource with clear scope and differentiation from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description explicitly says 'Use this when investigating recurring incidents or identifying root causes that span multiple tickets,' providing clear context for when to use. It also notes that filters use OR-ed semantics. However, it does not explicitly contrast with other list tools like swsd_list_incidents or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral context beyond annotations: it explicitly states this is a WRITE operation and that it does not retry on transient failures. This complements the `readOnlyHint=false` annotation and provides critical operational insight.
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 exceptionally concise: two sentences that convey purpose, parameter usage, alternative tool, and behavioral note. Every sentence 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.
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, good annotations, and full schema coverage, the description covers the essential aspects. It misses specifying the return value, but given no output schema, this is a minor gap. Otherwise, it is well-rounded.
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?
Input schema covers all three parameters with descriptions. The description adds extra semantic value for `is_private`, explaining its effect on visibility and default behavior. No additional detail is needed for `incident_id` or `body` given schema coverage, but the added context warrants a score above 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?
The description clearly states the tool's purpose: 'Add a comment to a SWSD incident.' It specifies a concrete verb and resource, and distinguishes from the sibling tool `swsd_update_comment` by explicitly directing users to use that tool for editing, ensuring no confusion.
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 guidance on when to use the `is_private` parameter and directs users to `swsd_update_comment` for editing after posting. While it lacks explicit 'when not to use' instructions, the context of sibling tools and the clear alternative is sufficient for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes beyond annotations by detailing the read-modify-write process, the distinction between read/write shapes, idempotency, and the lack of retry. No contradiction with 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?
Concise three-sentence description, front-loaded with the primary action. Every sentence adds essential information without 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?
Covers essential behavioral aspects for a write tool: process, idempotency, failure behavior. No output schema, but description is sufficient for an API with simple success/failure. Could mention return value, but not critical.
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%, but description adds value by explaining the auto-detection of internal vs. human-facing IDs via digit count, which is not in the schema description. This aids correct parameter usage.
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?
Clearly states the action: 'Attach a knowledge-base solution to an incident.' Differentiated from siblings like swsd_update_incident and swsd_create_incident by specifying the linking operation.
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?
Provides context on when to use (linking solutions), explains idempotent behavior, and states no retry on transient failure. Does not explicitly mention alternatives, but the sibling list and description imply no need for alternative guidance.
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?
Beyond annotations (readOnlyHint=false), the description adds that it is a WRITE operation without retry on transient failure, and only specified fields are sent. This is transparent but could detail failure handling.
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 concise (5 sentences) with no wasted words, front-loaded with the main action, and uses clear structure with bullet-like points for alternatives.
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 no output schema, the description covers key behavioral traits, alternatives, and custom field integration. It lacks error handling details but is complete for typical use.
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?
With 100% schema coverage, the description adds extra value for 'id' (auto-detection of format) and 'custom_fields' (validation, unsupported types, prerequisite tool call). Other parameters rely on schema descriptions.
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 explicitly states the verb 'Update' and the resource 'SWSD incident', and distinguishes from siblings by suggesting alternatives like swsd_update_incident_state and swsd_assign_incident for specific actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear usage guidance: when to use alternatives for state transitions, assignments, and comments; how to handle custom fields with a prerequisite call; and notes that only provided fields are changed.
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?
Discloses that it is a write operation, not idempotent, and does not retry on transient failure. Adds value over annotations by detailing retry behavior and that the created problem's id is returned.
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 sentences: first covers purpose and parameters, second covers usage and retry. Front-loaded, no redundancy.
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 7 parameters, no output schema, and no nested objects, the description sufficiently covers output (id returned), retry behavior, and parameter recommendations, making it complete for agent 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?
Schema coverage is 100%, but description adds prioritization of parameters (required vs strongly recommended), which aids parameter selection beyond schema descriptions.
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 (Create) and resource (SWSD problem) and differentiates from siblings by specifying the use case of promoting a recurring incident to a problem record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states required and recommended parameters, provides a clear usage scenario (promoting recurring incident), and gives retry guidance (verify with swsd_get_problem).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint are true. The description adds significant value by clarifying the tool is local-only, does not call SWSD, and includes documented rate limits, which goes beyond the annotation hints.
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 consists of two concise sentences that front-load the key purpose and behavioral constraints, with no superfluous information.
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 zero parameters, thorough annotations, and an output schema (though not detailed here), the description fully explains the tool's purpose and behavior, leaving no 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, so the description is not required to add param details. Baseline is 4. The description adequately explains what information is returned, which is sufficient.
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 returns server metadata (name, version, profile, enabled tools, base URL) with the verb 'Return', and distinguishes itself from sibling tools by specifying it is local-only and does not call SWSD.
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 explicitly notes 'Local-only — does not call SWSD', guiding the model to use it for server info without external API calls. It also mentions documented rate limits, but does not explicitly state when to avoid using it or provide alternatives, so it scores slightly below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, idempotent, and open-world. The description adds specific error types (401, 403, network error) and confirms return format, disclosing all relevant 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?
Two sentences: first states purpose, second details response. No fluff, every sentence adds value.
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 0 parameters, existing output schema, and simple purpose, the description covers all needed information for a health check 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?
No parameters, so description need not explain them. Schema coverage is 100% (empty). Baseline of 4 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 it verifies connectivity and authentication to SWSD. It distinguishes itself from CRUD/list siblings by being a health check with no side effects.
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 use before other operations ('make a minimal request') and explains error responses, but does not explicitly state when not to use or compare to alternatives. Still clear enough for its simple purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include idempotentHint: true and openWorldHint: true. The description confirms idempotency with 're-applying the same value is a no-op' and adds context about being a safer wrapper, which goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with front-loaded purpose, followed by precise usage details. Every sentence adds value without redundancy.
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 toggle tool with full annotation and schema coverage, the description provides all necessary context: usage, idempotency, and alternative paths. No gaps remain.
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% but the description adds meaningful details: incident_id auto-detects digit counts, task_id references a sibling tool, and completed maps to specific states. This enhances understanding 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 verb 'Mark' and resource 'SWSD incident sub-task as complete or incomplete', and distinguishes from siblings by noting that finer state control should use the SWSD UI.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly explains how to use the completed parameter to set or revert the state, warns against finer control, and identifies the tool as a safer wrapper for common transitions. Alternative direction is also provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and open-world. The description adds details about passthrough behavior, custom_fields_values inclusion, and the effect of detail_level. No contradiction with 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?
Three sentences that are front-loaded with the primary purpose, then provide critical usage guidance and parameter behavior. Every sentence adds value with no redundancy.
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 presence of an output schema and well-described parameters, the description covers all necessary aspects: purpose, when to use alternatives, parameter behavior, and special features. It is complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions, but the description adds value beyond the schema: for 'id', it explains auto-detection via digit count; for 'detail_level', it provides usage scenarios (e.g., 'show me everything'). This enhances 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 'Fetch one SWSD incident by numeric ID' with a specific verb and resource. It distinguishes from sibling tools like swsd_list_incidents (list) and swsd_update_incident (update), and mentions passthrough behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use swsd_list_incidents first if only a name or filter is available, noting that IDs are not guessable. Also provides guidance on when to use detail_level='long' (when user wants 'everything' or comments/attachments).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint. Description adds crucial context: which filters are client-side (email fields) with a verification date, server-side behavior, pagination caps, sorting defaults. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured, front-loaded with key info, and avoids fluff. Could be more bullet-pointed for readability, but it's efficient for its length and content.
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 19 parameters and 100% schema coverage, description covers all critical behavioral aspects: filtering, pagination, relationship to detail endpoint, client-side caveats, and security notes. Output schema mentioned but not needed in description.
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. Description adds significant value: explains client-side filtering for email fields, updated_within convenience alias, OR-ing of multiple values, group ID vs user ID, and sort defaults. Compensates beyond 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?
Clearly states the tool lists SWSD incidents with structured filters and pagination, distinguishes from swsd_get_incident for full detail, and explains the compact summary output. Very specific and helpful.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes when to use this tool (list incidents) vs. alternatives (swsd_get_incident for detail). Also explains filter behavior (client-side vs server-side) and OR semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Thoroughly describes internal behavior: calls swsd_get_me to get user email, client-side filter due to API limitation, and verification date. Annotations already mark read-only but description adds essential context about the workaround and potential side effects (e.g., returning entire tenant for fake emails).
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 fairly long but well-structured: first sentence states purpose, then explains internal behavior, then compares to sibling. Every sentence adds value, though some could be more concise. It front-loads key information.
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 complexity (18 parameters, API limitation, output schema exists), the description is highly complete. It covers the essential behavioral aspect (client-side filtering), error scenarios (fake email test), prerequisite tool mention, and sibling alternative. Missing no critical context.
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% with detailed parameter descriptions, so baseline is 3. The description adds value by explaining the overall context (client-side filter) and how parameters like assignee_email are handled, but does not significantly augment individual parameter semantics 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 lists incidents assigned to the authenticated user, using a specific verb and resource scope. It distinguishes itself from the sibling tool swsd_list_incidents by noting the limitation of server-side filtering and the client-side workaround.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool (for user-specific incidents) and when not ('For broader queries use swsd_list_incidents with assigned_to=<group_id>'). Also explains the API limitation and the internal behavior, providing clear guidance for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false, idempotentHint=false). The description adds critical behavioral detail: 'WRITE — does not retry on transient failure; the agent should verify with swsd_get_incident before retrying' and notes un-supported custom field types. No contradictions with 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?
Concise and well-structured: opens with the core action, then required/recommended fields, followed by behavioral notes (WRITE, retry behavior), then custom field instructions. Every sentence adds information, no redundancy.
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 9 parameters, no output schema, and the need to guide creation flow, the description covers all key aspects: prerequisites (required fields), error handling (verify before retry), custom field discovery and validation, and unsupported features. It also hints at the output (returned ID) for follow-up calls.
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 descriptions already explain most parameters. However, the description adds significant value by highlighting which parameters are strongly recommended, explaining the custom_fields array's validation rules in depth (date format, dropdown values, etc.), and clarifying that it does not support multi_picklist or User types.
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 SWSD incident' with explicit required and recommended fields. It distinguishes itself by naming follow-up tools (swsd_assign_incident, swsd_add_incident_comment) and contrasting with update/read tools, making its specific role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: required `name`, strongly recommended fields, when to use custom fields (after calling swsd_describe_custom_fields), and crucially, what to do on transient failure (verify with swsd_get_incident before retrying). Also clarifies unsupported custom field types (multi_picklist, User) and validates allowed types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent. The description adds value by detailing the return fields and the operational context (must be called first for personalized queries). No contradiction.
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 succinct sentences, front-loaded with purpose, then usage guidance. No wasted words.
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 zero parameters, strong annotations, and an output schema, the description provides all necessary context: what it returns, when to use it, and how it integrates with sibling tools.
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, so the baseline is 4. The description adds meaning by listing the fields returned, which is useful 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 it retrieves the SWSD user record for the token's owner, listing specific fields (id, email, name, etc.), which is a specific verb+resource. It distinguishes from siblings by indicating its role in resolving 'my' queries before using list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call this first when the request references 'me', 'my', or 'I', and explains the subsequent steps (pass id/email to filters or use swsd_list_my_incidents). It also clarifies the consequence of skipping this step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, idempotent, open-world. Description adds passthrough behavior, field details (HTML, plain text, custom_fields, comments, attachments), and how detail_level affects output. No contradiction.
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, front-loaded with purpose, no filler. Every sentence adds value.
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 output schema exists, description covers necessary usage and behavioral context. No gaps for a retrieval 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?
Schema covers both parameters with descriptions (100% coverage). Description adds usage context (ID auto-detection, long vs short) but schema already provides baseline meaning.
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?
Verb 'Fetch' clearly indicates retrieval, resource is 'SWSD solution by numeric ID'. Distinguishes from swsd_search_solutions (use if only have topic).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using swsd_search_solutions when only have topic, and suggests detail_level 'long' for additional data. Provides clear when-to-use and when-not-to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, but the description adds critical behavioral traits: async indexing (articles may not appear for minutes/hours) and that results are compact summaries with 240-character excerpts. This goes beyond annotations to disclose important limitations.
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 four sentences, front-loaded with purpose, then parameter specifics, output format, sibling reference, and an important caveat. Every sentence adds value with no 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 4 parameters (0 required), an output schema exists, and the tool's complexity is moderate, the description covers all necessary aspects: search functionality, output format, pagination hints, related tools, and a crucial async caveat. It is fully informative.
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%, giving baseline 3. The description adds conversational context (e.g., 'Empirically the canonical search parameter') and cross-references to swsd_list_categories, which adds value beyond the schema definitions.
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 it searches SWSD knowledge-base solution articles, specifies parameters for free-text and category filtering, and distinguishes from swsd_get_solution for full HTML retrieval. It also mentions the async indexing behavior, 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool (search solutions) and when to use swsd_get_solution (for full HTML). It also advises to use swsd_list_categories for category validation and to verify just-created articles with swsd_get_solution, providing clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint and idempotentHint, but the description adds valuable context: 'Returns the full problem detail as returned by SWSD (passthrough).' It also explains the auto-detection of ID type via digit count (from schema). No contradictions; description enhances transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each serving a distinct purpose: defining the tool, providing usage context, and detailing a parameter. It is front-loaded with the primary action and immediately useful information, with no wasted words.
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 complexity of two parameters with auto-detection and two detail levels, the description covers all essential aspects: what it does, when to use alternatives, how parameters work, and what output to expect (passthrough). An output schema exists, but the description still clarifies the nature of the return data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds significant meaning: for 'id', it explains the dual format (internal id vs. number) and auto-detection. For 'detail_level', it clarifies the trade-off between 'short' (faster/cheaper) and 'long' (more data). This goes beyond the schema's default and enum.
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 explicitly states 'Fetch one SWSD problem (ITIL problem record) by id or number.' It clearly identifies the verb (fetch) and resource (problem record). Additionally, it differentiates from the sibling tool swsd_list_problems by advising to use that for name-based searches, ensuring no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear when-to-use guidance: 'Use swsd_list_problems first if you only have a name or filter — IDs are not guessable.' It also instructs on when to use the detail_level parameter: 'Pass detail_level: "long" to include comments, audits, tasks, and time_tracks in one call.' This explicitly addresses alternatives and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, indicating safe idempotent read. The description adds valuable context: it returns specific fields, and explains the incident_id parameter accepts both internal id and human-facing number with auto-detection, which goes beyond the schema description.
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 just two sentences, very concise. First sentence states purpose and return fields; second sentence gives usage guidelines and alternatives. No wasted words, well-structured with front-loaded info.
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 simple tool (one parameter, annotations, output schema present), the description covers purpose, parameter nuances, return fields, and usage guidelines. It even mentions the alternative inline view in swsd_get_incident, making it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% description coverage, but the description adds extra meaning: it explains that incident_id accepts both internal id (>=7 digits) and human-facing number (<=6 digits) with auto-detection. This semantic nuance is not in the schema description.
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 sub-tasks on a SWSD incident, specifies returned fields, and distinguishes from sibling tools like swsd_create_incident_task and swsd_update_task_state. It also mentions that sub-tasks appear inline in swsd_get_incident with detail_level 'long'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use swsd_create_incident_task for adding sub-tasks and swsd_update_task_state for marking complete. It also notes that sub-tasks can be viewed inline via swsd_get_incident, providing clear guidance on when to use this tool vs alternatives.
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:

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

Score Badge

Copy to your README.md:

[![swsd-mcp MCP server](https://glama.ai/mcp/servers/mikimatsub/swsd-mcp/badges/score.svg)](https://glama.ai/mcp/servers/mikimatsub/swsd-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/mikimatsub/swsd-mcp'

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