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

Annotations already declare readOnlyHint=false (write operation) and destructiveHint=false (non-destructive). The description adds the explicit warning 'WRITE — does not retry on transient failure,' which is useful but somewhat redundant with the readOnlyHint. It lacks detail on what happens on failure (no retry) or any side effects beyond the comment creation, but the annotations cover the safety profile, so a 3 is appropriate.

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

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

The description is concise and front-loaded: it states the primary action first, then the key parameter behavior, then the alternative tool, and finally the safety note. Every sentence earns its place, with no filler. It could be slightly more concise by moving the warning to the end, but it's already efficient.

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

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

Given the tool's moderate complexity (3 params, no output schema, annotations cover safety), the description is nearly complete: it explains the action, the parameter semantics, when to use the alternative, and the failure behavior. The only gap is that it doesn't describe what the response looks like (since no output schema), but for a simple add operation this may not be critical. A 4 is justified.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description reinforces the meaning of is_private (default false, internal-only) and explicitly adds the auto-detection logic for incident_id (digit count), which is a valuable behavioral nuance not fully captured in the schema's description. However, body is plain text/HTML, which the schema already states, so the description adds minimal extra value.

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

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

The description clearly states the action (add a comment), the target resource (SWSD incident), and the key functional detail (visibility via is_private). It distinguishes itself from the sibling tool swsd_update_comment by explicitly naming it as the alternative for editing comments, 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.

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

The description explicitly states when to use this tool (to add a comment) and when not to (to edit a comment, use swsd_update_comment). It also explains the behavioral nuance of is_private (default false = visible to requester), which is a clear usage guideline for when to set it to true for internal-only comments.

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

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

Annotations already mark this as a non-read-only, non-idempotent, destructive write. The description adds value beyond that by explicitly stating 'WRITE — does not retry on transient failure,' which is a critical behavioral trait not present in the annotations. It also explains the safety-wrapper rationale.

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

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

Three sentences with no filler: the action is front-loaded, the wrapper context is concise, and the prerequisite lookup is stated in one clear instruction. Every sentence earns its place.

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

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

For a simple two-parameter write tool with complete schema coverage and annotations, the description covers the essential operational context: what it does, how it relates to siblings, how to find valid assignees, and the retry behavior. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters, including the id auto-detection rule and the assignee availability requirement. The description adds no new parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'Assign an SWSD incident to an agent by email.' It also distinguishes itself from the broader swsd_update_incident by framing this as a narrower wrapper, so an agent can immediately tell what this tool is for.

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

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

The description explicitly instructs the agent to use swsd_list_users with available_for_assignment_only=true to find valid assignees first, and frames the tool as a safer alternative to swsd_update_incident. This gives clear when-to-use and how-to-prepare guidance.

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

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

Discloses write behavior, non-retry on transient failures, and recommends verifying with get_incident before retrying. Also details custom field validation types, providing operational guidance beyond the annotations (which only indicate readOnly=false).

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

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

The description is well-structured, front-loading the core action and then covering recommendations, error handling, and custom fields without redundancy. Each sentence adds value, and the length is appropriate for the complexity.

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

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

Covers essential aspects: required/recommended fields, follow-up usage, error handling, and custom field discovery. For a tool with 9 parameters, it provides sufficient context, though it doesn't mention rate limits or output format beyond ID.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning by marking required vs recommended parameters and explaining custom_fields usage and validation, going beyond raw schema definitions.

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

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

States a specific verb and resource: 'Create a new SWSD incident.' It clearly distinguishes from siblings like create_service_request by resource type, and mentions required and recommended fields, making its purpose unambiguous.

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

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

Provides clear context for when to use (to create an incident), and instructs on handling custom fields (discover via describe_custom_fields). It does not explicitly contrast with alternative tools like create_service_request, but the resource type makes the usage clear.

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

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

The description discloses that this is a WRITE operation that does not retry on transient failure, adding operational nuance beyond the annotations. It also states that the created task is returned, which is valuable since there is no output schema. This meaningfully extends what annotations alone provide.

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

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

Three compact sentences: purpose, parameter summary, and behavioral note. The purpose is front-loaded, and each sentence adds distinct value with no filler. The 'WRITE — does not retry on transient failure' note is especially information-dense.

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

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

The description covers the core operation, required inputs, return value, and retry behavior, which is adequate for a straightforward create tool without an output schema. It omits potential error cases or prerequisite conditions, but the annotations and full schema coverage fill in most gaps, so the description is nearly complete.

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

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

Schema description coverage is 100%, and every parameter already has a detailed description. The tool description's parameter summary (e.g., 'plain text or HTML', 'ISO 8601') duplicates the schema rather than adding new meaning, so it meets the baseline but does not exceed it.

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

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

The description opens with a specific verb and resource: 'Create a new sub-task on a SWSD incident.' This clearly identifies the operation and distinguishes it from sibling tools like swsd_create_incident, swsd_add_incident_comment, and swsd_create_service_request. No ambiguity about what resource is being acted upon.

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

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

The description gives clear invocation context by stating required and optional parameters, so an agent knows what is needed to use the tool. However, it does not explicitly name alternatives or specify when not to use this tool versus sibling create/update tools, so it stops short of full routing guidance.

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

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

Annotations already establish readOnlyHint=false and idempotentHint=false, but the description adds specific behavioral detail: it labels the tool as 'WRITE', states it does not retry on transient failure, and instructs the agent to verify with `swsd_get_problem`. It also discloses that the created problem's id is returned. This goes beyond the annotations by describing the exact failure-handling behavior, though it doesn't mention other potential side effects beyond creation.

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

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

The description is compact (about four sentences) and front-loads the core action and required field, then provides usage context and failure handling. Every sentence contributes information—there is no filler or repetition of obvious schema details. The structure flows logically from what → when → failure behavior.

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

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

Given 7 parameters and no output schema, the description covers all critical aspects: what the tool does, required fields, what it returns (id), when to use it, and how to handle failures. It even references the verification tool. No additional information is needed for an agent to call it correctly; the schema fills in the remaining parameter details.

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

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

The schema covers 100% of parameters with descriptions, but the description adds prioritization: it flags `name` as required and `description`, `priority`, and `category` as strongly recommended. This hierarchy isn't in the schema and helps the agent decide which parameters matter most, adding value beyond the structured schema definitions.

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

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

The description uses a specific verb and resource ('Create a new SWSD problem (ITIL problem record)'), clearly identifies the required `name` field, and immediately distinguishes it from incident creation by explaining the use case ('promoting a recurring incident to a problem record'). It also hints at the follow-up `swsd_get_problem` call, making its role unambiguous among many incident and problem tools.

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

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

Explicitly states when to use the tool ('Use this when promoting a recurring incident to a problem record') and gives practical guidance on required/recommended fields. It also advises verification with `swsd_get_problem` after failure, effectively telling the agent when not to simply retry, which is clear usage direction not present in other definitions.

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

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

The description goes well beyond the annotations: it discloses that this is a WRITE operation that 'does not retry on transient failure', mandates verification via swsd_get_incident before retrying, and notes the auto-set `is_service_request: true` behavior and supported value types. This is exactly the kind of operational context (non-idempotency, verification protocol) that idempotentHint=false only hints at. No contradiction with annotations — 'WRITE' aligns with readOnlyHint=false and the retry caution aligns with idempotentHint=false.

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

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

The description is dense (roughly 180 words) but well-ordered: purpose first, then prerequisite workflow, then parameter semantics, then the WRITE/retry warning, then the custom_fields note, then validation scope. Each sentence earns its place with a distinct fact. Minor redundancy exists — the validation note ('Validated for Text, Dropdown, Number, Checkbox, and Date types') also appears in the schema's custom_fields description — so it is not maximally lean, but it is well structured.

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

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

For a non-idempotent write tool with 5 parameters and prerequisite discovery calls, the description covers purpose, workflow prerequisites, parameter relationships, retry/verification behavior, and type validation, and the output schema handles return-value documentation. What is missing is an explicit pointer to the generic sibling swsd_create_incident for non-catalog cases and any error-behavior detail (e.g., failure modes for invalid dropdown values). Highly actionable, but not exhaustive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-parameter context — request_variables' custom_field_id equals the catalog item variable's id and values must be stringified to match the variable's kind — but the schema already documents these relationships in detail (e.g., 'Get it from swsd_get_catalog_item -> item.variables[*].id'). The description reinforces but does not materially extend the schema's parameter documentation.

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

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

The description opens with a specific verb-resource pair — 'Submit a SWSD catalog request, creating an incident' — and adds the distinguishing flag `is_service_request: true (auto-set by SWSD on this endpoint)`, which differentiates it from the sibling swsd_create_incident. An agent can tell exactly what this tool does and how it differs from its nearest sibling without opening the schema.

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

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

The description gives an explicit prerequisite workflow: use swsd_list_catalog_items to find catalog_item_id, swsd_get_catalog_item to inspect variables, and swsd_describe_custom_fields before setting custom_fields. It also prescribes the post-call verification step ('verify with swsd_get_incident before retrying'). The only gap is that it never explicitly says when NOT to use this tool in favor of swsd_create_incident for non-catalog incidents.

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

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

Annotations already provide readOnlyHint=true and idempotentHint=true, so the description need not restate safety. It adds useful read behavior beyond the schema: default returns active fields only, passing active_only:false includes retired fields, and filtering is recommended because the surface can be large. This gives the agent additional context about how the tool behaves at scale, though no auth or rate-limit details are provided.

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

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

The description is long but every sentence carries useful information, including the v2 write note that prevents misuse. It is front-loaded with the core purpose and return fields, and the later details about writes and unsupported types are clearly scoped to a separate but related concern. Slightly longer than strictly necessary, but efficient for a config-relevant tool.

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

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

For a read-only list tool with five optional parameters, a full input schema, and an output schema present, the description provides everything an agent needs: what the schema returns, how to include retired fields, why and how to narrow results, and how it relates to sibling write tools. No important behavioral gap low-visible.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a little context by showing how to use active_only:false and why to filter by scope/module, but it does not introduce new parameter-level meaning beyond what the schema already gives. The value is mostly reinforcement rather than additional semantics.

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

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

The description opens with the specific verb and resource ('List the SWSD tenant's custom-field schema') and enumerates exactly what each field returns (id, name, type, required, scope, module, allowed values, help_text). This unmistakably identifies the tool's purpose among sibling tools, many of which operate on incidents or solutions.

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

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

Usage is clearly contextualized: it is 'useful for understanding tenant configuration and documenting integrations', with guidance to filter by scope/module because tenants may have 100+ fields. The v2 note also directs agents to the alternative tools for writes (swsd_create_incident, swsd_update_incident, etc.), so the agent knows this tool is for reading schema rather than writing custom fields.

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

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

Beyond the readOnly/idempotent annotations, the description richly discloses the response behavior: it returns the item plus a `variables` array describing the form schema, including `id`, `name`, `kind`, and `options`. It even explains that options are newline-separated and that the full top-level item is available to power users. This gives the agent a concrete mental model of what the tool does and returns.

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

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

The description is only a few sentences and every sentence earns its place: main action first, then how the variables work, then parameter/return guidance for power users. It is dense yet readable, with no filler or duplication of the schema.

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

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

Given a single well-documented parameter, strong annotations, an available output schema, and rich behavioral description, the definition is complete. It even covers the downstream integration with create-user service request and explains the detail an agent needs to make sense of the response.

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

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

The input schema already fully documents the only parameter with 100% coverage, including the fact that the id comes from swsd_list_catalog_items. The tool description adds general context about id being used for catalog lookup, but does not materially improve on the schema's own description. Baseline 3 is appropriate.

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

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

The description states a clear verb and resource: 'Get a single SWSD catalog item by id', and adds important scoping by saying 'single' rather than list, distinguishing it from list_catalog_items. It also clarifies the tool's unique value through the `variables` form-schema content, making its purpose unmistakable.

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

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

The description gives concrete usage context: the variables tell you which fields to populate when submitting a service request, and each variable id should be passed to the create-service-request tool as `custom_field_id`. It does not explicitly say when not to use it versus list_catalog_items, but the 'by id' scoping plus the creation workflow guidance is enough for an agent to select it appropriately.

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

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

The description goes beyond annotations by disclosing that the result is a passthrough from SWSD, includes custom_fields_values when present, and that 'long' adds comments, attachments, audits, SLA data, and resolution. This helps the agent anticipate the response shape and breadth without contradicting the read-only, idempotent, non-destructive hints.

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

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

Three tight sentences deliver purpose, return behavior, workflow routing, and parameter guidance with no filler. The most important facts are front-loaded, and every sentence earns its place.

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

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

The output schema handles return structure, the annotations handle safety/idempotency, and the description covers lookup strategy, ID constraints, and detail-level tradeoffs. For a read-only fetch-by-ID tool, there is no material gap preventing correct invocation.

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

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

The schema already documents both parameters fully with 100% coverage, including the ID format/auto-detection rule and the detail_level behavior. The description adds little parameter-level meaning beyond reinforcing those points, so a baseline score of 3 is appropriate.

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

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

The description states a specific verb ('fetch'), resource ('one SWSD incident'), and selection criterion ('by numeric ID'). It also distinguishes itself from the sibling list tool by noting that swsd_list_incidents should be used when only a name or filter is available, 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.

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

It explicitly routes the agent to swsd_list_incidents when it lacks an ID, and explains why IDs are not guessable. It also gives clear guidance on when to use detail_level 'long' (include comments, attachments, audits, SLA data, and resolution), so the agent can decide correctly at call time.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value beyond annotations by disclosing the return content (the full field list) and the critical sequencing dependency — that the returned id/email must be passed into follow-up filters. This behavioral context about usage flow is genuinely additive.

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

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

Purpose is front-loaded in the first sentence, and each subsequent sentence earns its place — usage triggers, follow-up steps, and the alternative. It runs slightly long, but the verbosity is justified because this tool has a subtle usage pattern (must be invoked first for 'my X' queries) that warrants explanation. No wasted sentences.

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

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

Despite zero parameters and a simple signature, the tool has a non-obvious invocation pattern and an output schema (which covers return-value details). The description covers everything an agent needs: what it returns (field enumeration), when to call it first, how to chain the output into downstream tools, and the failure mode if skipped. Nothing essential is missing.

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

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

The tool takes zero parameters (schema coverage trivially 100%), so the description carries no parameter burden. Per rubric, 0-param tools get a baseline of 4. The description correctly communicates that identity is derived from the token's owner rather than from parameters, which is the key semantic an agent needs to understand.

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

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

States a specific verb ('Get') + resource ('SWSD user record for the token's owner') and enumerates the returned fields (id, email, name, title, role, department, site, group_ids, assignment status). It clearly distinguishes from siblings — it's the only tool that fetches the current token owner's record, versus swsd_list_users which lists all users.

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

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

Explicitly specifies when to call it ('Call this first' when the request mentions 'me', 'my', or 'I') with concrete examples ('my tickets', 'tickets in my group', 'tickets assigned to me'). It names the alternative (swsd_list_my_incidents) that does this in one call, effectively stating when-not-to-use, and explains the consequence of skipping this step ('my X' queries cannot be answered correctly).

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

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive. The description adds valuable context: it is a passthrough to SWSD (returning raw output), IDs are not guessable, and detail_level controls the inclusion of comments/audits/tasks/time_tracks. This goes beyond the structured annotations, informing the agent about output nature and constraints.

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

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

Three concise sentences, each earning its place: the main action, the routing guidance, and the optional detail_level tip. The critical scoping information is front-loaded, and there is no redundant wording.

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

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

With a full output schema, rich param descriptions, and annotations covering safety and idempotency, the description completes the picture by addressing how to get the right record (list first if no ID) and how to optimize the call (detail_level). Nothing essential for an agent to call this safely and effectively is missing.

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

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

Schema coverage is 100% and both parameters already have clear descriptions (id auto-detection, detail_level enum with meaning). The description slightly reinforces detail_level usage but largely repeats schema content. The baseline of 3 applies because the schema carries the burden, and the description adds minimal extra semantic value.

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

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

The description clearly states 'Fetch one SWSD problem (ITIL problem record) by id or number', specifying the verb, resource, and identifier type. It distinguishes from siblings by explicitly naming swsd_list_problems as the alternative when only a name or filter is available, preventing confusion with the listing and creation tools.

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

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

Explicitly instructs to use swsd_list_problems first when lacking an ID, since 'IDs are not guessable'. Also provides guidance on optional detail_level to include more data in one call. This gives clear when-to-use and when-not-to-use direction relative to siblings.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so safety is well-covered. The description adds valuable context: it is 'cheaper' than the alternative, and it describes the structure of each audit entry, helping an agent understand what to expect. It doesn't fully describe pagination or output format, but annotations lower the burden.

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

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

Three sentences with no waste. The purpose is stated first, followed by concrete use cases and a cost comparison. Information is front-loaded and every sentence earns its place.

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

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

The description covers the purpose, use cases, alternative tools, and the content of returned audit entries. With an output schema present and annotations declaring read-only behavior, nothing an agent needs to decide whether to call this tool or interpret its results is missing.

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

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

Schema description coverage is 100%, so all parameters are already documented in the schema. The tool description repeats the list of object_type values but adds no additional semantic value beyond what the schema provides. A baseline of 3 is appropriate given high schema coverage.

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

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

The description states a specific verb and resource ('List the audit log for a SWSD record') and defines the expected content (action, message, user, timestamp). It clearly distinguishes this from other tools by focusing on audit history, and explicitly notes it as an alternative to 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.

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

Provides explicit when-to-use guidance with concrete questions ('who changed this ticket?', 'what happened since I last looked?') and a cost-based decision between this tool and swsd_get_incident with detail_level=long. This gives an agent clear routing criteria.

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

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

Annotations already declare readOnlyHint, openWorldHint=false, idempotentHint, destructiveHint=false. The description adds value by noting it does not call SWSD (local-only), preventing agents from expecting live data. It also mentions including upstream rate limits, which is useful context. Slight gap: no mention of output shape, but output schema exists, and no behavioral edge cases.

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

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

Concise three-sentence description. Front-loaded with what it returns, then clarifies local-only and added value (rate limits). No fluff or duplication of schema/annotations.

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

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

For a zero-parameter tool with an output schema and annotations covering safety, the description is complete. It adds the crucial 'does not call SWSD' context and mentions rate limits, which are otherwise inferable. Nothing missing for correct invocation.

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

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

The tool has 0 parameters, so the schema is trivially complete. The description does not need to explain parameters. A baseline of 4 is appropriate for a no-parameter tool with full coverage; there's nothing to clarify.

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

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

The description clearly states it returns server info (name, version, profile, enabled tools, base URL) with a specific verb 'Return' and resource 'SWSD MCP server's name...'. It distinguishes itself from siblings by noting it's local-only and does not call SWSD, and it includes rate limits. It's distinct from read operations on incidents, users, etc.

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

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

The description states it's local-only, indicating it's for server introspection rather than SWSD data retrieval. It implies when to use (need server info, rate limits) and contrasts with tools that call SWSD. Does not explicitly exclude specific siblings but the local-only note is clear guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds valuable context beyond annotations: it discloses passthrough behavior (raw SWSD response), lists key fields returned, and explains the ID auto-detection nuance. The note 'IDs are not guessable' further clarifies why a search-first workflow is necessary.

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

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

Three sentences, each carrying essential information: what the tool does, what it returns, and usage guidance for parameters. The most important fact (fetch by ID) is front-loaded, and no words are wasted. It is compact yet comprehensive.

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

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

Given the 2-parameter schema with rich descriptions, a full output schema, and safety annotations, the description covers all essential aspects: purpose, prerequisites (search first), return content, and optional detail_level. Nothing critical for invoking the tool correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful extra guidance by explaining that IDs are not guessable and recommending swsd_search_solutions as the source for the id parameter. However, it largely echoes the schema's detail_level description, so the added value is modest beyond the non-guessability hint.

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

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

The description opens with a specific verb and resource: 'Fetch one SWSD solution by numeric ID.' It clearly distinguishes this from sibling tools like swsd_get_incident and swsd_search_solutions by focusing on 'solution' as the resource. It also specifies the exact return shape, which removes ambiguity about what the tool does.

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

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

The description explicitly instructs to use swsd_search_solutions first if the user only has a topic, stating that IDs are not guessable. It also provides clear guidance on when to pass detail_level: 'long' to include attachments, audits, and tags. This leaves no doubt about when to choose this tool or how to adjust its behavior.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by disclosing the specific error behavior: returns ok=true on success, and on failure explains error types (401=bad token, 403=insufficient permission, network error=unreachable). This goes beyond the annotations, giving agents actionable diagnostics. It also mentions 'minimal request,' implying lightweight execution. No contradiction with annotations; readOnlyHint aligns with the verification/read nature.

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

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

The description is two sentences, front-loaded with the core purpose. The first sentence states the action and outcome; the second details the return contract. Every word earns its place—no filler, no repetition of annotations, and no tangential details. It is appropriately concise for a simple health check tool.

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

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

For a zero-parameter tool with a straightforward purpose, the description covers all needed context: what it does, what success returns (ok=true), and what failure returns (detailed error strings). The output schema presence means the description doesn't need to enumerate all fields, and it already explains the key return semantics. Nothing an agent needs to invoke and interpret this tool correctly is missing.

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

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

The tool takes zero parameters, and schema coverage is 100% (vacuous). The baseline for tools with no parameters is 4, and the description correctly avoids pretending to add parameter semantics. It does not mislead about arguments because none exist. There is nothing further the description could add about parameters, so a score of 4 is appropriate.

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

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

The description states a specific purpose: 'Verify connectivity and authentication to SWSD by making a minimal request.' This clearly identifies the verb (verify), resource (SWSD connectivity/auth), and scope. It distinguishes itself from siblings like swsd_get_server_info or swsd_get_me, which serve other roles. The phrasing is unambiguous and immediately conveys what the tool does.

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

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

The description implies usage as a connectivity/auth pre-check, but it does not explicitly state when to use it versus alternatives or when not to. For instance, it never says 'use this before other SWSD calls' or 'use this only for troubleshooting connection.' The context is clear enough to infer its purpose, but explicit guidance on when to invoke it (e.g., before a batch of operations) is missing. Thus, the usage is implied rather than explicitly guided.

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

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

Annotations already indicate a non-read-only, idempotent, non-destructive operation. The description adds significant context beyond that: the exact read-modify-write sequence, the distinction between write and read shapes, the preservation of existing links, and the explicit note that it does not retry on transient failure. This enriches the agent's understanding of side effects and reliability.

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

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

Four sentences, each delivering essential information without redundancy: action, operational mechanism (fetch-read-append-put), idempotency, and retry policy. The most critical detail (write shape) is front-loaded, and every sentence earns its place.

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

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

The description covers the operation sequence, idempotency, write shape, and failure handling, which is adequate for a write tool without an output schema. It lacks explicit mention of success criteria or response format, but given the tool's complexity and the detailed schema, it is nearly complete.

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

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

Schema coverage is 100%, with both parameters thoroughly described including digit-count auto-detection. The tool description itself does not add parameter-specific details, but since the schema fully handles semantics, the baseline of 3 applies.

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

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

The description states a specific verb 'Attach' and resource 'knowledge-base solution to an incident'. It clearly distinguishes this tool from siblings by mentioning the write shape ('solution_ids') vs the read shape, and emphasizes idempotency, leaving no ambiguity about its function.

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

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

The description provides clear context for when to use this tool (to link a solution to an incident) and implies its uniqueness through the read-modify-write mechanism. However, it does not explicitly name alternatives (e.g., swsd_update_incident) or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds domain context about catalog items but does not disclose much additional behavioral detail, such as pagination behavior or visibility rules; however, with strong annotations, this gap is acceptable.

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

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

Three sentences, all purposeful: the first states the core action, the second gives essential domain context, and the third routes the agent to the correct next steps. There is no filler or redundancy.

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

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

For a read-only listing tool, the description, combined with 100% schema coverage, rich annotations, and an existing output schema, is complete. It tells the agent what the items represent, how to inspect one, and how to submit a request afterward.

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

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

Schema description coverage is 100%, so every parameter, including page, site, query, state, per_page, and department, is already documented in the schema. The description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List catalog items available in SolarWinds Service Desk.' It also adds semantic context by defining items as offerable service request templates with input variables, and it distinguishes itself from the sibling swsd_get_catalog_item, which inspects a single item's variables.

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

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

The description explicitly names the workflow: use swsd_get_catalog_item to inspect variables, then swsd_create_service_request to submit. This tells an agent not only what this tool does but where it fits among its siblings, providing clear selection guidance.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: the hierarchy semantics (parent_id links), the fact that only immediate children are returned, and the full field set — all useful for an agent deciding whether this tool satisfies a lookup.

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

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

Three tight sentences: purpose, return shape plus hierarchy semantics, and a concrete use case. Every sentence earns its place, the primary verb is front-loaded, and there is zero filler or repetition of schema content.

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

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

For a read-only list tool with an output schema, full parameter documentation, and comprehensive safety annotations, the description covers everything an agent needs: what it lists, what it returns, the hierarchy behavior, and when to call it. Pagination and parameter bounds are already carried by the schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so page, query, and per_page are already documented with types, defaults, and bounds, making the baseline of 3 appropriate. The description only indirectly relates to the query parameter via the category_name validation use case, adding no direct format or syntax guidance beyond the schema.

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

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

The description opens with a specific verb and resource ('List SWSD incident/solution categories'), immediately distinguishing it from sibling list tools targeting other resources (incidents, users, catalog items). It also enumerates the exact return fields (id, name, parent_id, immediate children, default_assignee_id) and explicitly notes the hierarchy, leaving no ambiguity about what the tool does.

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

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

The final sentence gives an explicit use case — 'Use this to validate category_name before swsd_create_incident or swsd_update_incident' — which tells an agent exactly when to invoke this tool. However, it does not state when NOT to use it or compare it against alternatives such as swsd_list_catalog_items, so exclusions are left to inference.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds that it returns id, name, description (likely already in the output schema) and frames it as a validation step. It doesn't add substantial behavioral context beyond the annotations, and it does not contradict them.

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

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

Two concise sentences, immediately front-loaded with the core action ('List SWSD departments'). The purpose is delivered in one extra sentence with zero waste. Every word earns its place.

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

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

With a complete output schema and annotations covering safety and idempotency, the description adds the intended use case and return fields. It doesn't mention pagination or filtering, but those are already documented in the schema. For a simple, read-only list tool, this is sufficient.

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

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

All three parameters (page, query, per_page) have full descriptions in the schema (coverage 100%), so the baseline is 3. The description does not add any additional parameter details or constraints beyond what the schema already provides.

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

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

Description clearly states the verb 'List' and the resource 'SWSD departments', and clarifies it returns id, name, description. It distinguishes from other list tools (e.g., swsd_list_sites, swsd_list_categories) by naming the specific resource and adding a use case. The purpose is unmistakable.

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

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

Provides explicit guidance: 'Use this to validate department_name before incident write tools.' This tells when to invoke the tool. It doesn't explicitly mention alternatives or when not to use it, but the primary use case is well defined among many sibling list tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safe read behavior is covered. The description adds meaningful behavioral detail by stating exactly what the response includes (id, name, description, disabled, member_count), which is not covered by annotations. No contradictions exist between the description and annotations.

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

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

The description is three clear, concise sentences with no wasted words. The purpose is front-loaded, followed by returned fields and a use case. Every sentence contributes meaningful value and the structure is easy to parse.

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

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

For a simple listing tool with an output schema and annotations covering safety, the description is complete. It states the purpose, the returned fields, and the practical context (ticket triage). Pagination behavior is left to the schema parameters, which are fully documented. There is no missing information an agent would need to invoke this tool correctly.

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

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

The schema provides 100% description coverage for all three parameters (page, query, per_page), including defaults, constraints, and descriptions. The description does not add any parameter-level semantics beyond what the schema already offers, so the baseline of 3 applies as described in the rubric.

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

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

The description clearly identifies the tool as listing SWSD groups (assignment teams), with a specific verb and resource. It further distinguishes the tool by specifying the return fields (id, name, description, disabled, member_count), making it clear this is a reference-data listing tool and not an incident or user tool. The parenthetical '(assignment teams)' adds immediate clarity about what groups are.

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

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

The description provides a concrete use case: 'useful for understanding team structure when triaging tickets.' This gives clear context for when to use it. However, it does not explicitly name alternative tools or state when not to use this tool, but the resource 'groups' is unique among siblings so the guidance is adequate.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds concrete output contract detail ('Returns id, body, is_private, author_email, author_name, created_at') and distinguishes mutation via add, adding useful behavior beyond the structured hints.

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

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

Two sentences with no filler. The main action is front-loaded, return fields are compactly listed, and the sibling pointer is one clear sentence.

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

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

For a read-only, idempotent list endpoint with an output schema and well-documented parameters, the description is sufficiently complete. Sibling differentiation, return contract, and core resource scope are all covered.

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

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

Schema description coverage is 100% and each parameter is well documented, including the nuanced incident_id format and pagination bounds. The description itself adds little about parameters, but the schema carries the full load, so baseline 3 is appropriate.

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

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

Description opens with 'List comments on a SWSD incident', which is a specific verb + resource that clearly distinguishes this tool from incident management and mutation tools. It also explicitly contrasts with the sibling add-comment tool, making selection unambiguous.

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

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

The description provides immediate usage context: list comments rather than add them, with sibling alternative named. It lacks a fuller 'when to use' formulation or mention of when not to use update/delete paths, but the clear contrast with add covers the key alternative.

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

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

Annotations already indicate read-only and idempotent. The description adds valuable behavior like client-side application of assignee_email/requester_email (with verification date) and the note that other filters narrow server-side. It doesn't over-explain but covers critical pitfalls.

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

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

The description is moderately long but every sentence adds value. First sentence states purpose, then return format, then filter semantics, then crucial client-side note. Slightly verbose but well-structured and front-loaded.

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

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

For a tool with 19 parameters and an output schema, the description covers return format, points to detail tool, explains filter semantics, client-side caveats, and indexing-time behavior. Nothing essential is missing for an agent to use it correctly.

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

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 extra semantics: repeated-key array OR-ed behavior, client-side vs server-side filtering, and the async-indexing caveat for query. This goes beyond schema descriptions.

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

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

The description clearly states the tool lists SWSD incidents with structured filters and pagination, and explicitly differentiates it from swsd_get_incident (full detail) and swsd_list_my_incidents. The verb 'list' + resource 'SWSD incidents' is precise.

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

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

Explicitly instructs to call swsd_get_incident for full detail, explains client-side vs server-side filtering behavior, and distinguishes when to use this vs alternatives. Provides concrete guidance on filter semantics and caveats.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the description doesn't need to repeat that. It adds value beyond annotations by clarifying that the returned data is also available inline in a long incident detail response and by naming the exact state enums ('New' / 'In Progress' / 'Completed'). This helps the agent reason about the data's origin and overlap.

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

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

Three sentences, each earning its place: one states the operation and result shape, one names related mutation tools, and one gives a lightweight alternative lookup path. It is front-loaded and free of unnecessary filler.

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

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

For a simple read-only list operation with one well-documented parameter and annotations covering safety, there is nothing material missing. The output schema presumably defines the return shape, and the description supplies the only needed selection context. This is complete enough for a capable agent.

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

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

The input schema already covers the sole parameter incident_id completely, including the internal-id vs. human-facing-number distinction and auto-detection logic. The description adds no further parameter-level meaning, so baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List sub-tasks on a SWSD incident.' This clearly distinguishes it from list_incidents, list_incident_comments, and other sibling tools. The list of returned fields reinforces exactly what the tool produces, removing any ambiguity about scope.

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

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

The description gives explicit routing guidance: use swsd_create_incident_task to add a sub-task and swsd_update_task_state to change state. It also notes that sub-tasks appear inline in swsd_get_incident with detail_level: 'long', giving the agent a known alternative path for retrieving the same data.

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

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

The description discloses behaviors well beyond the safe-read annotations: it internally calls swsd_get_me, filters response client-side, and reveals that /incidents.json silently ignores assignee_email/requester_email filters, supported by a dated verification. This conveys the critical failure mode (fake email returns the entire tenant) that annotations could never express.

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

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

The purpose is front-loaded in the first sentence and each subsequent sentence carries essential information: the internal mechanism, the API bug, and the routing to the sibling tool. Slightly dense — the parenthetical verification detail could be trimmed — but nothing is padding.

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

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

For a complex 18-parameter tool with no required params and an output schema, the description covers purpose, mechanism, and alternatives well. One notable gap: it does not explain how client-side narrowing interacts with pagination (e.g., per_page could yield fewer results after filtering), which an agent might need to reason about multi-page fetching.

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

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

With 100% schema description coverage, the baseline is 3, and the description adds genuine value by warning that assignee_email/requester_email filters are silently ignored server-side — even though requester_email appears in the schema with a functional-sounding description. It also clarifies which params are routed server-side, but it does not explicitly tell agents to avoid the requester_email param.

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

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

The description states a specific verb+resource+scope: 'List incidents assigned to the authenticated user.' It clearly distinguishes itself from swsd_list_incidents and explains the internal mechanism (via swsd_get_me, filtered client-side), so there is no ambiguity about what this tool does relative to its siblings.

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

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

The description explicitly names the alternative ('For broader queries use swsd_list_incidents with assigned_to=<group_id>') and the selection condition, with the added rationale that group filtering works server-side while assignee filtering does not. The agent is told precisely when this tool is the right choice.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond that: repeated-key array filter semantics (OR-ed values), compact summary output vs. full detail, and pagination support, all of which inform how an agent will interpret results.

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

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

Three tight sentences with no filler: the first states the core action and result format, the second points to the sibling for full detail, and the third explains filter semantics and the intended use case. All content earns its place.

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

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

The description is complete for a read-only list tool. It covers the result summary shape, the fallback for deeper detail, filter behavior, and the appropriate investigative context. The output schema and annotations handle the remaining structured details, and no required parameters exist.

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

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

The input schema has 100% parameter description coverage, so the baseline is 3. The description adds extra meaning by explaining the SWSD repeated-key array semantics for filters, which is not present in the schema and is essential for constructing correct multi-value array parameters.

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

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

The description opens with a specific verb and resource: 'List SWSD problems (ITIL problem records)', which clearly distinguishes this from incident-focused siblings like swsd_list_incidents. It also names swsd_get_problem as the complementary detail-retrieval tool, so an agent can immediately tell what this tool does and what it does not do.

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

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

The description explicitly states when to use the tool: 'Use this when investigating recurring incidents or identifying root causes that span multiple tickets.' It also gives a clear alternative by directing the caller to swsd_get_problem for full details of a single row, providing both a use case and a routing rule.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds that it returns id, name, description and clarifies the semantic of roles, but does not disclose new behavioral traits such as pagination behavior (which is already in the schema). It does not contradict the annotations.

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

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

The description is two sentences with zero waste. It front-loads the primary purpose and immediately explains utility. No redundant or promotional language.

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

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

The tool is simple, with full schema parameter descriptions, an output schema for return values, and annotations covering safety. The description adds the use case for triaging permission tickets, which is sufficient for an agent to decide when to invoke it. No critical information is missing.

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

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

Schema description coverage is 100%, so all three parameters (page, query, per_page) already have clear descriptions. The tool description does not add any parameter-specific meaning beyond what the schema provides, so the baseline 3 applies.

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

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

The description states a specific verb ('List') and resource ('SWSD roles') with a clarifying parenthetical ('permission profiles'), making the tool's purpose clear. It does not explicitly differentiate from sibling list tools like swsd_list_users, but the resource name is sufficiently distinct.

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

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

The description provides a clear use context: 'useful when triaging permission-related tickets.' However, it does not explicitly state when NOT to use it or name any alternatives, so it lacks exclusions but offers a clear context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, which cover the safety profile. The description adds value by stating the exact fields returned and the purpose of validation, providing context beyond the annotations. It does not contradict annotations and adds meaningful behavioral context about the output shape and intent.

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

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

Three sentences, all information-dense with zero filler. The purpose and return fields are front-loaded, the use case is one clear sentence. Every sentence earns its place without redundancy or boilerplate.

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

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

For a list tool with an output schema and only optional parameters, the description covers purpose, return shape, and a concrete usage scenario. Pagination is handled by schema defaults, and the read-only nature is captured by annotations. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so all three parameters (page, query, per_page) are already well-documented with types, defaults, and constraints. The description does not add any parameter-specific meaning beyond reinforcing the 'query' as a substring filter. Baseline of 3 is appropriate when the schema carries the full parameter documentation burden.

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

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

States a specific action ('List') on a clear resource ('SWSD sites') with explicit detail on the returned fields and a stated use case. It clearly distinguishes itself from the many other 'list' tools in the sibling set by narrowing to physical office/branch locations. No ambiguity about what this tool does.

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

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

Provides explicit when-to-use guidance: 'Use this to validate site_name before incident write tools.' This is clear and actionable. It does not explicitly name alternatives or when not to use it, but the use case is specific enough to guide an agent. A small deduction for not mentioning alternatives, though the context signals show many list tools exist.

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

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

Annotations (readOnlyHint, idempotentHint, destructiveHint=false) already establish the non-mutating, safe profile, so the bar is lower. The description adds value by noting the tool's role as a pre-update context fetch. With annotations covering the safety profile, the description's modest behavior statement is sufficient. Credit for the 'before adding/updating' context orientation, though it doesn't describe pagination or return format beyond schema.

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

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

Two sentences, zero waste. The first sentence states exactly what it lists, and the second gives the usage context. No filler or redundancy.

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

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

High schema coverage (100%) plus output schema means parameters and return values are documented elsewhere. The description supplies the missing contextual guidance—when to call this (before add/update operations) and what parent object types it covers. Complete for an agent to select and invoke.

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

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

Schema coverage is 100%, so all four parameters (id, object_type, page, per_page) are documented in the schema. The description adds the conceptual context that `id` refers to a parent record of the listed types, reinforcing but not extending the schema. Baseline 3 is appropriate.

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

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

Clear verb+resource construction: 'List SWSD time entries for an incident, problem, change, or release.' The description specifies the exact entity (time entries), scope (parent record types), and distinguishes it from siblings like swsd_log_time and generic list tools. An agent can immediately tell what this does.

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

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

States clear context: 'Use this before adding/updating time when you need existing work-log context.' This orients the agent to invoke list before mutation. However, it doesn't name the alternative (swsd_log_time / swsd_update_time_track) explicitly or provide exclusions/constraints on when not to use it. Clear but could be more explicit.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds useful behavioral detail such as exact email matching and assignment-filter semantics, but it does not disclose potential pagination behavior or rate limits, so it adds only modest context beyond the annotations.

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

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

Three tightly written sentences with the purpose and returned fields front-loaded, followed by two high-value usage notes. No filler or redundant restating of the schema is present.

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

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

The definition is complete for a simple read-only list operation: it states the resource, lists return fields, flags the key filtering use cases, and the schema covers pagination and remaining parameter details. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so a baseline of 3 applies. The description goes beyond the schema by linking available_for_assignment_only to the swsd_assign_incident workflow and by explaining that email performs an exact one-user lookup, which genuinely helps an agent choose and set parameters.

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

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

The description starts with a specific verb and resource, 'List SWSD users,' and enumerates the exact returned fields, making the tool's purpose immediately clear. It is also the only user-listing tool in the sibling set, so there is no ambiguity about what resource it operates on.

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

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

The description gives two concrete usage contexts: setting available_for_assignment_only to find valid assignees for swsd_assign_incident, and setting email for an exact single-user lookup. It does not explicitly name an alternative tool, but for a unique list-users tool the guidance is clear and actionable.

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

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

The description explicitly labels the operation as a WRITE, states that it honors SWSD_WRITE_MODE, and notes that transient failures are not retried. These details go beyond the annotations and give the agent actionable expectations about side effects and failure behavior.

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

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

The description is two sentences with no filler: the first states the core purpose, and the second conveys safety and retry behavior. It is front-loaded with the action and resource, making it easy for an agent to scan.

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

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

For a simple write tool with all parameters required and fully described in the schema, the description supplies the remaining operational context: it is a write, respects environment mode, and does not retry transient failures. No output schema exists, but the description does not need to explain return values here because the core invocation details are covered.

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

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

With 100% schema description coverage, the schema already documents all four parameters. The description adds the useful note that minutes_parsed is the exact SWSD field name, and it restates which fields are required, but it does not add significant meaning beyond the schema.

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

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

The description clearly states the action ('Log time against') and the specific resources (incident, problem, change, release), making it distinct from sibling tools like swsd_list_time_tracks and swsd_update_time_track. The required fields are also listed, reinforcing what invocation entails.

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

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

The description gives no explicit guidance about when to use this tool versus alternatives such as swsd_list_time_tracks or swsd_update_time_track. It does not state prerequisites, follow-up steps, or which sibling to choose for modifying time entries.

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

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

The description discloses a non-obvious behavioral trait: search is asynchronously indexed, so recently created or updated articles may not appear for minutes or hours. It also states the return shape (compact summaries with 240-char truncated excerpts), which adds context beyond the readOnlyHint/idempotentHint annotations. 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.

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

Three sentences front-load the core action and parameters, then cover the key alternative and the indexing caveat. Every sentence carries distinct information, the async-indexing note is clearly marked, and there is no filler or repetition.

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

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

Given a rich output schema and strong annotations, the description covers everything an agent needs: what is searched, how to filter, what the return looks like, when to call an alternative, and a critical timing caveat. The routing to swsd_get_solution and mention of swsd_list_categories in the schema round out the contextual picture.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the roles of query and category in plain language but does not add meaningful parameter details beyond the schema (e.g., page, per_page are left to the schema). No parameter semantics are missing, but the description adds little beyond what the schema already provides.

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

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

The description opens with a specific verb and resource: 'Search SWSD knowledge-base solution articles.' It explicitly distinguishes itself from swsd_get_solution by noting that the search returns compact summaries while the sibling returns full HTML bodies, making the tool's role unambiguous among a large sibling list.

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

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

The description gives direct routing guidance: use swsd_get_solution for the full HTML body of any result, and use swsd_get_solution to verify a just-created article because of async indexing. It also explains the exact combination of parameters to pass (query and/or category), clearly separating this tool from alternatives.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the write nature is known. The description adds valuable context beyond annotations: the is_private limitation, the explicit 'WRITE' tag, and the note that it does not retry on transient failure. 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.

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

Three sentences with zero fluff. The main action is front-loaded, followed by the key constraint and a behavior warning. Every sentence earns its place, making it efficient and easy to scan.

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

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

For a simple update operation with no output schema, the description covers the essential aspects: the parameters, the visibility limitation, and the retry behavior. It does not describe the return value, but that is commonly omitted for updates and not critical given the simplicity. The tool's low complexity and full schema coverage make this adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description merely names the parameters ('Pass incident_id, comment_id, and the new body') without adding new semantics. The schema already fully documents body type, incident_id format, and comment_id constraints. The description does not go beyond that.

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

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

The description opens with a clear verb and resource: 'Update the body of an existing SWSD incident comment.' It specifies exactly what is modified (body) and distinguishes it from sibling tools like swsd_add_incident_comment (create) and swsd_update_incident (update incident fields). 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.

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

The description states the required parameters and gives a clear operational constraint: the is_private flag cannot be changed, requiring delete-and-recreate instead. It also flags the write behavior and absence of retry on transient failure. It does not explicitly name alternatives, but the context makes the usage domain clear.

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

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

Annotations already flag this as a non-read-only, destructive, non-idempotent write, and the description adds valuable beyond-annotation behavior: it sends only provided fields, does not retry on transient failure ('WRITE — does not retry'), and replaces the description whole. No statement contradicts the annotations.

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

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

The description is dense but well structured: purpose first, then alternatives, then operational warning, then custom-field details. Every clause earns its place and code-formatted identifiers improve scannability.

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

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

For an 8-parameter, no-output-schema write tool, the description covers selection, prerequisites, and side-effect semantics almost completely. It only omits the shape of the response or success/failure indicators; an agent might need that for a follow-up step, but this is a minor gap.

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

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

Schema coverage is 100%, so the baseline is 3; however, the description adds the patch semantics (only provided fields sent) and reinforces the custom_fields payload shape and the need to discover field names/allowed values first. This is useful beyond the individual property descriptions.

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

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

The description opens with a specific verb and resource: 'Update an existing SWSD incident.' It immediately explains the partial-update contract ('Pass `id` and any fields to change') and differentiates itself from sibling tools for state transitions, assignment, and comments. This gives an agent a clear identity for the tool without opening the schema.

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

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

It explicitly tells the agent when to avoid this tool: 'For state transitions prefer swsd_update_incident_state... for assignment prefer swsd_assign_incident; for comments use swsd_add_incident_comment.' It also specifies a prerequisite for custom fields ('call swsd_describe_custom_fields first'). This is model routing guidance.

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

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

Annotations already carry the mutation profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the bar is lower. The description adds genuine value beyond them: 'WRITE — does not retry on transient failure' discloses a retry policy absent from the annotations, and the tenant-specific state caveat warns about environment-dependent behavior. No contradiction — the description's 'WRITE' and 'Transition' align with readOnlyHint=false and destructiveHint=true.

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

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

Four purposeful sentences, front-loaded with the core action and ending with the most safety-critical warning (no retry). The state-value list is somewhat redundant with the schema's state description, and the paragraph could be tightened with structure, but every sentence otherwise earns its place and nothing is fluff.

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

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

For a two-parameter mutation with full schema coverage and a complete annotation set, the description covers the action, the sibling rationale, the prerequisite call, tenant-specific state caveats, and no-retry behavior. The only material gap: there is no output schema and the description never hints at what a success or error response looks like — a minor omission for a write operation.

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

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

Schema description coverage is 100%: the id parameter already explains internal-id vs human-facing-number auto-detection, and the state parameter already documents valid tenant values including the common list. The description's state examples and 'tenant-specific' warning largely restate the schema's own state text, so it adds minimal semantic value beyond the baseline 3 that high schema coverage earns.

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

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

The description opens with a specific verb+resource+object ('Transition an SWSD incident to a new state') and immediately distinguishes itself from the raw update sibling by calling itself a 'safer wrapper around swsd_update_incident.' Listing concrete example states ('Assigned', 'Resolved', 'Closed') lets an agent know exactly the operation's scope and how it differs from the 35 sibling tools.

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

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

It gives an explicit sequencing prerequisite — 'Call swsd_get_incident first to see the current state' — and steers the agent toward this tool over the broader update by framing it as a wrapper that 'narrows the agent decision surface.' It stops short of a 5 because it never names when-not conditions for overlapping siblings like swsd_assign_incident or swsd_update_task_state.

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

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

The annotations already convey write (readOnlyHint=false), destructive (destructiveHint=true), and idempotent (idempotentHint=true) traits. The description adds beyond those by stating the precise effect: `completed: false` reverts to 'New', re-applying the same value is a no-op, and the tool is described as a 'safer wrapper' for the common transition. No contradiction with annotations exists.

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

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

The description is compact and front-loaded: the core action is in the first clause, usage instructions follow, and the WRITE/idempotent note is packed into a short final phrase. Every sentence earns its place with no redundant filler.

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

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

Given the three required parameters are fully documented in the schema and there is no output schema, the description covers what an agent needs to invoke it correctly: purpose, exact parameter effects, when to avoid it, and behavioral guarantees. Sibling tools like swsd_list_incident_tasks provide the context for obtaining task_id.

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

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

Schema description coverage is 100%, with detailed descriptions for all three parameters, including incident_id's auto-detection logic and task_id's source. The description's 'Pass `completed: true`...' line mostly restates the schema's completed parameter semantics, so it adds little beyond the schema baseline.

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

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

The description opens with a specific verb and resource: 'Mark a SWSD incident sub-task as complete or incomplete.' It clearly distinguishes this tool from the sibling swsd_update_incident_state by focusing on sub-task state transitions, and explicitly excludes finer states like 'In Progress'.

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

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

The description explicitly states when to use the tool: for the common done/not-done transition via `completed: true/false`. It also gives a clear exclusion and alternative: 'For finer state control (e.g., "In Progress"), use the SWSD UI directly.' This leaves no ambiguity about when to choose this tool over alternatives.

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

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

Annotations already flag the tool as non-read-only and destructive, and the description reinforces this with 'WRITE' while adding genuinely new operational details: it 'honors SWSD_WRITE_MODE and does not retry on transient failure.' This mode-sensitivity and retry policy are exactly the behavioral context the annotations do not carry.

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

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

Two sentences totaling roughly 28 words, with the purpose front-loaded and parameter/behavior notes packed into a tight second sentence. Every clause earns its place and nothing repeats schema content.

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

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

The description covers purpose, target object scope, payload parameters, and two non-obvious runtime behaviors (WRITE_MODE sensitivity and no retry on transient failure), which is substantial for this complexity level. It does not describe the return value or error behavior when the time entry does not exist, a minor gap given there is no output schema.

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

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

Schema coverage is 100%, so all five parameters already have descriptions, earning the baseline 3. 'Pass name and/or minutes_parsed' adds a small semantic hint that these two are the update payload while the others are locators, but the schema's own field descriptions already convey that distinction.

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

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

States a specific verb ('Update') and resource ('existing SWSD time entry on an incident, problem, change, or release'), immediately distinguishing it from creation (swsd_log_time) and listing (swsd_list_time_tracks) siblings. The object-type scope is explicit, so an agent knows exactly what this tool targets.

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

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

The phrase 'Update an existing... time entry' clearly implies this tool is for modifying existing entries rather than creating new ones, and 'Pass name and/or minutes_parsed' gives direct invocation guidance. No sibling is named explicitly and there are no when-not-to-use exclusions, so guidance is clear but relies on inference.

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

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

Beyond the annotations, the description discloses two behavioral constraints: transport-dependent parameter selection and the SWSD_WRITE_MODE gate that can block the write. readOnlyHint=false is consistent with the explicit 'WRITE' marker, and destructiveHint=false matches the additive nature of an upload. 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.

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

Three short sentences (~50 words), each earning its place: purpose and scope, parameter selection rule, and write-mode gating. The purpose is front-loaded and nothing duplicates the schema's field descriptions.

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

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

For a 5-parameter write tool with full schema coverage and safety-relevant annotations, the description covers purpose, record-type scope, parameter choice, and the write gate. The only gap is undisclosed success/failure or response behavior, but no output schema exists and the annotations already carry the safety profile.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds selection semantics the per-field schema leaves inferential: content_base64 and file_path form a mutually exclusive either/or choice determined by transport, which the description resolves explicitly for the agent.

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

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

States a specific verb ('Upload') with a clear resource ('attachment') and enumerates the full scope of supported target record types (incident, problem, change, release, solution, hardware asset, other asset, configuration item). None of the 34 sibling tools perform uploads, so this tool is immediately distinguishable without opening the schema.

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

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

Provides explicit invocation context: content_base64 is for hosted/HTTP clients, file_path is allowed only on stdio transport, and the operation honors SWSD_WRITE_MODE. There is no sibling upload tool to route between, so tool-vs-alternative guidance is unnecessary; the transport selection rules are actionable and precise.

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