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

Annotations already declare readOnly=false, idempotent=false, destructive=false, so the safety profile is known. The description adds genuinely non-obvious behavior: 'WRITE — does not retry on transient failure', which tells the agent to handle failures itself rather than assume retry semantics. It stops short of describing auth requirements or the response payload.

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, front-loaded with the action, then the privacy flag, then the edit alternative and write caveat. No filler; every clause carries routing or behavioral information.

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

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

With annotations present and no output schema, the description covers the essential unknowns: write semantics, no-retry behavior, privacy toggle, and the edit path. It does not say what the call returns (e.g., a new comment id), which is a minor gap for a create 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% and the schema already documents is_private's default and incident_id's id-vs-number auto-detection. The description restates the is_private default but adds no syntax or format detail beyond the schema, 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?

States a specific verb and resource ('Add a comment to a SWSD incident') and explicitly distinguishes itself from the sibling swsd_update_comment, which handles post-hoc edits. An agent can route between add vs. edit without opening either 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?

Names the alternative (swsd_update_comment) and the condition that selects it ('to edit a comment after posting'), and gives explicit guidance on when to set is_private. It does not cover interaction with swsd_list_incident_comments, but the create-vs-edit routing is the important one and it is stated.

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

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

Annotations already declare the write/destructive/open-world profile, so the bar is lower, and the description adds a trait the annotations do not: 'WRITE — does not retry on transient failure,' which tells the agent a failure is terminal and retrying is its own responsibility. It doesn't cover auth requirements or a response shape, but the added operational context is meaningful.

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, all front-loaded: purpose first, then sibling relationship, then prerequisite, then the write caveat. No filler and every clause carries distinct information.

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

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

For a two-parameter mutation with no output schema, the description covers the write semantics, the failure behavior, and the assignee-discovery prerequisite. It does not describe what a successful assignment returns or what happens if the email is not an assignable user, leaving a small 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 description coverage is 100%, so both id and assignee_email are already fully documented, including the id format auto-detection and the assignee_email validity constraint. The description's only added semantics is the pointer to swsd_list_users for finding valid assignees, which is usage guidance rather than new parameter meaning. 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?

States a specific verb and resource ('Assign an SWSD incident to an agent by email') and immediately positions itself against the sibling swsd_update_incident by explaining it is a narrower alternative. An agent can distinguish it from swsd_update_incident without opening either 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?

Explicitly routes the agent: it names the alternative (swsd_update_incident) it wraps, tells the agent to use swsd_list_users with available_for_assignment_only=true to find valid assignees first, and states the decision surface is deliberately narrowed to 'who gets this ticket.' This is when-to-use plus a prerequisite workflow.

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 non-read-only, non-idempotent, open-world behavior, but the description adds genuinely new operational context the annotations cannot convey: it does not retry on transient failure and the agent should verify with swsd_get_incident before retrying. It also discloses the return of the incident ID and the supported/unsupported custom-field types (multi_picklist and User excluded), which is real behavioral disclosure beyond the structured fields.

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

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

Front-loaded with purpose, then requirements, return value, retry caveat, and the custom-fields note — a sensible ordering with no filler sentences. It is dense and the final sentence largely restates the custom_fields schema description, which keeps it from a 5.

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 9-parameter write tool with no output schema, the description covers the essentials: required vs. optional inputs, the returned ID, non-idempotent retry handling, cross-tool prerequisites, and custom-field type limitations. There is no meaningful gap an agent would hit when invoking it.

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 earns above that by prioritizing parameters (required `name`, strongly recommended `description`/`requester_email`/`priority`/`category_name`) and by explaining the `custom_fields: [{name, value}]` shape and the need to discover field names first. It doesn't add format or validation detail beyond what the schema already states.

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?

Opens with a specific verb+resource ("Create a new SWSD incident") and immediately scopes the required vs. strongly recommended fields, so the agent knows exactly what this tool produces. It never differentiates itself from the sibling swsd_create_service_request, which is the one plausible confusion in this toolset, so it falls short of a 5.

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?

Explicit routing guidance throughout: assign at creation via assignee_email or defer to swsd_assign_incident, call swsd_describe_custom_fields before setting custom fields, and use swsd_get_incident to verify before retrying. It also names the follow-up tools that consume the returned ID, giving the agent a clear workflow path.

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 non-readOnly, non-idempotent, non-destructive, open-world. The description adds genuinely non-obvious context beyond them: 'The created task is returned for follow-up calls' and 'WRITE — does not retry on transient failure,' which tells the agent to handle retries itself.

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, front-loaded with the action, then required/optional params, then the write-behavior note. No filler and every clause carries information.

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

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

For a 5-param write tool with no output schema, it covers required/optional fields, the return of the created task, and non-retry behavior. It stops short of stating permission/auth requirements or validation failure modes, but is otherwise sufficient to invoke 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% and the schema is richer than the prose (e.g. incident_id auto-detection by digit count, due_at ISO patterns, length limits). The description's required/optional list and ISO 8601 note add little beyond it, 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 opens with a specific verb+resource ('Create a new sub-task on a SWSD incident'), which cleanly distinguishes it from siblings like swsd_create_incident, swsd_list_incident_tasks, and swsd_update_task_state.

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

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

It enumerates required (`incident_id`, `name`) and optional (`description`, `due_at`, `assignee_email`) parameters, which implies usage, but gives no explicit when-to-use guidance or when a caller should prefer a different sibling tool.

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?

Goes beyond the annotations by disclosing retry semantics: 'WRITE — does not retry on transient failure; the agent should verify with swsd_get_problem before retrying.' This matches and enriches the idempotentHint=false/readOnlyHint=false structured hints. It doesn't cover auth/permission requirements or any side effects beyond creation, but the retry and verification guidance is concrete operational value.

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?

Front-loaded with the action, then required vs. recommended fields, then return value, then usage context, then the write/retry caveat. Every sentence contributes distinct information with no 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?

Despite having no output schema, it states 'The created problem's id is returned for follow-up calls,' covering the return value. All 7 parameters are schema-documented, the write/retry behavior is disclosed, and the verification path is named, so 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 coverage is 100%, so the baseline is 3, and the description earns above that by adding a recommendation ranking the schema does not carry: 'Required: name. Strongly recommended: description, priority, category.' That tells the agent which optional fields materially affect record quality, which is information not present in the schema's required list.

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 problem (ITIL problem record)') and distinguishes the artifact from the sibling incident/service-request creation tools by qualifying it as an ITIL problem record. The parenthetical clarifies the domain concept so the agent doesn't confuse it with swsd_create_incident.

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 gives the trigger condition: 'Use this when promoting a recurring incident to a problem record so root-cause analysis and known-error tracking can be tied to multiple incidents.' It also names the follow-up path (verify with swsd_get_problem before retrying). It stops short of naming an explicit alternative (e.g. use swsd_create_incident for a one-off occurrence), so it's clear context without full when-not routing.

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?

Goes well beyond the annotations by disclosing that calls do NOT retry on transient failure and prescribing verification via swsd_get_incident before retrying, plus a real API constraint (numeric requester ids are rejected, so an email is required to file on behalf of another user). This is exactly the non-obvious write-behavior context annotations cannot convey.

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

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

Purpose and the write/retry warning are front-loaded, and every sentence carries operational content. It is a dense single paragraph with some parenthetical overlap against the schema, so slightly less scannable than ideal.

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?

An output schema exists, yet the description still states what is returned (the created incident id) for chaining calls, and covers prerequisites, write semantics, failure handling, and per-type value formats. Nothing an agent needs to invoke this 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 coverage is 100%, so the schema already documents all five parameters (baseline 3). The description adds some cross-referencing value by linking request_variables.custom_field_id to the catalog variable's id and stressing stringification by variable 'kind', though most of this duplicates the schema text.

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 ('Submit a SWSD catalog request, creating an incident with is_service_request: true'), which clearly distinguishes it from the sibling swsd_create_incident. The agent immediately understands the endpoint's effect 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?

Explicitly routes the agent: use swsd_list_catalog_items to find catalog_item_id, swsd_get_catalog_item to inspect variables, and swsd_describe_custom_fields before passing custom_fields. It also names the follow-up tools (swsd_get_incident, swsd_assign_incident) and states the condition for each.

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, destructiveHint=false, and openWorldHint, so the safety profile is covered. The description adds substantial context: returned field attributes, the default active-only behavior, the 100+ field scale, and v2 write support/limitations, going beyond structured 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 core listing purpose and return shape are front-loaded in the first two sentences, followed by parameter guidance. The v2 NOTE is long and tangential to invoking this read-only listing tool, though it provides useful cross-tool context, so it slightly dilutes conciseness.

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 annotations covering safety, a complete input schema, and an output schema, the description needs only to orient the agent. It does that and more: it explains the returned schema, default filtering, and write limitations, leaving no material gap for invoking or interpreting the listing.

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 five parameters are already documented. The description reinforces active_only and scope/module filtering and gives a reason (tenant may have 100+ fields), but it adds no new syntactic or format details 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 first sentence states a specific verb ("List") and resource ("SWSD tenant's custom-field schema"), and the returned fields are enumerated. It is clearly distinguishable from sibling tools like swsd_list_incidents or swsd_get_incident because it targets tenant field configuration, not ticket data.

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

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

The description gives a concrete motivation ("understanding tenant configuration and documenting integrations") and operational guidance for active_only and scope/module filtering. It does not name a when-not condition or direct alternative for listing fields, though the v2 note routes write needs to other 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, openWorldHint, idempotentHint, and destructiveHint=false. Building on that, the description adds useful behavioral context about the response: variables represent a form schema, each variable has id/name/kind/options, the id maps to custom_field_id for create-service-request, and the full top-level item is passed through. It stops short of discussing auth, rate limits, or error behavior, but it adds substantive 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?

The description is front-loaded with the core action and purpose, then layers in usage and variable detail. It is relatively long, and some variable-shape detail overlaps with the output schema, but the content is purposeful and directly helps an agent decide and act.

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 one-parameter read tool with a full output schema and comprehensive annotations, the description is complete: it explains what is returned, how the returned variables should be used with create-service-request, and where the id comes from. No critical information needed 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%, and the single id parameter is already fully documented in the schema as 'Catalog item id from swsd_list_catalog_items.' The description repeats the same source without adding format, constraints, or alternative meanings for the input parameter, so 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 and resource: 'Get a single SWSD catalog item by id, including its variables.' It distinguishes itself from the sibling list tool by emphasizing 'single ... by id' and by pointing to 'swsd_list_catalog_items' as the source of the id, so an agent can route correctly without opening schemas.

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 clear context for use: 'Use the variables to know which fields to populate when submitting a service request,' and it names the downstream tool (create-service-request). It does not explicitly cover when not to use this tool or state prerequisites, so the guidance is strong but not exhaustive.

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/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real value beyond that: the response is a passthrough of SWSD's payload including custom_fields_values when present, and there is an explicit speed/cost tradeoff between short and long detail levels. It stops short of noting auth or rate-limit 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?

Three front-loaded sentences with no filler; the identity, the pre-requisite, and the option are each addressed once. The detail_level sentence is near-duplicative of the schema's own wording, which is the only slack in an otherwise tight definition.

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 passthrough getter with annotations carrying the safety profile and an output schema carrying the return shape, this is nearly complete. Coverage of auth/permission requirements and behavior on a non-existent or out-of-scope ID is the remaining 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 description coverage is 100%, and the schema already documents the digit-count auto-detection for id and the full enum semantics of detail_level. The description's detail_level sentence largely restates the schema text, adding only the motivating example ("show me everything about ticket X"), so baseline 3 is correct.

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 ("Fetch one SWSD incident by numeric ID") and immediately scopes the return ("full incident detail as returned by SWSD (passthrough)"). This is clearly distinguishable from the many sibling list_* tools, and the numeric-ID qualifier separates it from name/filter-based lookup.

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?

Names the alternative and the selecting condition explicitly: "Use swsd_list_incidents first if you only have a name or filter — IDs are not guessable." It also gives a second conditional rule for detail_level: "long" when the user wants comments/attachments/audits, default short for speed/cost.

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 safety is covered. The description adds real behavioral context beyond them: that skipping this step makes 'my X' queries fail, which is a non-obvious failure mode. It doesn't discuss rate limits or token/permission failure modes, so not a 5.

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?

Front-loaded with purpose, then usage, then consequence — a good ordering. It runs slightly long with the field enumeration and parenthetical examples, but nearly every clause carries routing information.

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

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

An output schema exists, so return values need not be re-explained, yet the description still names the key fields an agent needs to wire into assignee_email/requester_email. For a zero-param, read-only lookup, 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?

Zero parameters, so baseline 4 applies. The description lists the fields the record carries (id, email, name, role, group_ids, assignment status), which usefully signals what downstream filters can consume, though the output schema already defines these.

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 ('Get the SWSD user record for the token's owner') and enumerates the payload fields returned. It is clearly distinct from siblings like swsd_list_users (arbitrary users) and swsd_list_my_incidents (the one-call shortcut for the same intent).

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

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

Gives an explicit trigger ('when the request mentions "me", "my", or "I"'), a concrete prescription ('Call this first'), and names the two alternatives (swsd_list_incidents filters, or swsd_list_my_incidents) with the condition that selects each.

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/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds real context beyond that: results are an unmodified SWSD passthrough, IDs are not guessable, and detail_level: "long" fans out into comments, audits, tasks and time_tracks in a single call. It stops short of noting rate limits, auth scope, or what happens on an unknown id.

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, each doing distinct work — what it returns, how to find the id, and the optional expansion mode. No filler and the primary purpose is 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?

An output schema exists, so return-shape explanation is not required, and the description still usefully characterises the payload as a passthrough. Combined with the routing hint and detail_level guidance, an agent has everything needed to invoke it correctly; only error/not-found behavior is unaddressed.

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 the id digit-count rule and the enum meanings are already documented in the schema. The description's contribution ("IDs are not guessable", the long-mode contents list) largely restates that, so it sits at the baseline rather than adding new 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?

States a specific verb+resource ("Fetch one SWSD problem (ITIL problem record)") and the keying method (by id or number). It is immediately distinguishable from swsd_list_problems and the other list/get siblings in the toolset.

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 routes the agent: "Use swsd_list_problems first if you only have a name or filter — IDs are not guessable." It also names the condition that selects the richer mode (detail_level: "long"), so both the tool-vs-sibling choice and the in-tool option choice are resolved.

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 cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower; the description adds real value by enumerating what each entry contains (action values, message format, actor, timestamp). It does not mention pagination ceilings or ordering, but the schema covers page/per_page defaults.

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?

Front-loads the purpose, then usage, then the sibling tradeoff, then a required-param note. Every sentence carries distinct information; no 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?

An output schema exists, so return-value documentation isn't required, yet the description still sketches entry structure, which is a bonus. For a read-only, 4-param list tool this covers everything an agent needs to select and invoke it.

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 earns above that by clarifying object_type semantics ('incidents' for tickets, 'solutions' for KB articles) and listing accepted values, which helps an agent map user intent to the enum. The id dual-format nuance is left to 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?

States a specific verb+resource ('List the audit log for a SWSD record') and immediately scopes it by naming the sibling it substitutes for (swsd_get_incident with detail_level=long). An agent can distinguish this from the incident-listing and detail tools without opening any 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?

Gives concrete use cases ('who changed this ticket?', 'what happened since I last looked?') and an explicit alternative-selection rule: cheaper than swsd_get_incident with detail_level=long when only audit history is needed. When-to-use and the tradeoff against a specific sibling are both stated.

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

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

Annotations already declare readOnly/openWorld=false/idempotent, so the bar is lower, yet the description adds meaningful context: it is local-only and does not call SWSD, and it surfaces upstream rate limits. It stops short of detailing the return shape, though an output schema 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?

Two sentences, both front-loaded: the returned fields lead, followed by the local-only constraint and the rate-limit note. No filler.

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

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

The tool has no parameters and an output schema that documents return values, so the description need not explain them. The key behavioral fact (local-only, no SWSD call) is disclosed, making it complete for an agent to call 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?

Zero parameters, so the baseline is 4. Schema coverage is 100% and there are no parameters whose semantics require elaboration in the description.

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 (Return) and resource (the SWSD MCP server's name, version, profile, enabled tools, base URL host), so an agent knows exactly what it yields. It does not explicitly differentiate itself from sibling swsd_health_check, leaving that inference to the agent.

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 'Local-only — does not call SWSD' clause implies usage (when you need config/limits without hitting the API), but there is no explicit when-to-use, when-not-to-use, or named alternative versus swsd_health_check. Usage must be inferred.

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, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds genuinely new behavioral context: the response is a raw SWSD passthrough with dual HTML/plain-text description fields, IDs are unguessable, and "long" detail pulls attachments, audits and tags in a single call. It stops short of noting pagination or error behavior, but for a single-record read the gaps are minor.

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 load-bearing: identity/scope, return shape, and the two behavioral caveats (search first, long detail). The routing advice is front-loaded where an agent will act on it.

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?

Output schema exists and annotations cover the safety profile, so the description only needs to cover usage routing and the detail_level tradeoff, which it does. Nothing an agent needs to invoke this 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 documents the id auto-detection (>=7 digit internal id vs <=4 digit human number) and the detail_level enum with its default. The description's detail_level note largely restates the schema, adding no new syntax, format, or edge-case guidance. 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?

States a specific verb and resource ('Fetch one SWSD solution by numeric ID') and immediately enumerates what the returned object contains (description HTML, description_no_html, custom_fields_values, comment count, attachment metadata). An agent can distinguish this from swsd_search_solutions without opening either 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?

Explicitly routes the agent: 'Use swsd_search_solutions first if you only have a topic — IDs are not guessable.' It also states the condition for escalating to detail_level: "long" (attachments/audits/tags in one call), giving both when-to-use and an 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description goes beyond them by decoding the outcome surface — ok=true on success and specific error semantics (401 bad token, 403 insufficient permission, network error unreachable) — which is genuinely useful failure-triage context an agent cannot get from annotations alone.

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 tightly written sentences with the primary purpose front-loaded and the return contract immediately after. No filler or repetition of structured fields.

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-param, fully-annotated health probe with an output schema, the description supplies exactly the missing piece — how to interpret success and failure codes. Nothing an agent needs to invoke and reason about the result is absent.

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, so the baseline is 4. There is nothing to document and the description correctly omits any parameter discussion.

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?

Specific verb+resource ('Verify connectivity and authentication to SWSD') with the mechanism disclosed (makes a minimal request). It is clearly distinguishable from siblings like swsd_get_me or swsd_get_server_info, which fetch data rather than test reachability.

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 a diagnostic/preflight use case but never states when to call it versus alternatives (e.g., 'use before other calls when credentials may be stale'). No exclusions or sibling routing are given, so usage is only inferable.

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?

Goes well beyond annotations by disclosing the read-modify-write sequence (fetch, read existing solutions, append, PUT), the write-shape vs read-shape distinction (`solution_ids` vs `solutions`), idempotency semantics ('returns success without modifying'), and no-retry-on-transient-failure behavior. The no-retry and shape details are not covered by annotations, adding genuine value.

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?

Front-loaded with the core action, then tightly packs the mechanism, shape distinction, idempotency, and failure behavior into a few dense sentences. Nearly every clause 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 stateful mutation tool with no output schema, the description covers mechanism, side effects, idempotency, retry posture, and shape needed to call it correctly. Annotations and rich schema cover the rest, 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 the schema already documents both parameters thoroughly. The description adds the `solution_ids` write-shape naming context, which is useful API detail, but no additional syntax beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Attach a knowledge-base solution to an incident') and the description makes clear this is a specialized link operation rather than a generic incident update. An agent can distinguish it from swsd_update_incident and swsd_search_solutions without opening a 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 implies the use case (link a KB solution to an incident) but offers no explicit when-to-use vs alternatives guidance in the description itself; the routing hint ('use swsd_search_solutions') lives only in the parameter schema. Usage is inferable but not spelled out.

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, openWorldHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds useful context about what a catalog item is and how it fits the workflow, but does not disclose pagination behavior, rate limits, or return shape. Given annotations carry the safety burden, 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?

Three sentences, front-loaded with the primary action, then a clarifying definition, then routing guidance. Every sentence earns its place with no 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 read-only list tool with an output schema present, annotations covering safety, and 100% schema description coverage, the description is complete. It defines the resource, its role in the workflow, and the sibling tools to chain with. Return values are covered by the 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 description coverage is 100% with all six parameters documented inline (including the SWSD name mapping note for query). The description adds no parameter-level detail beyond what the schema already provides, so 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?

States a specific verb + resource ('List catalog items available in SolarWinds Service Desk') and clarifies what an item represents (offerable service request template with input variables). It is clearly distinguishable from sibling tools like swsd_get_catalog_item and swsd_create_service_request.

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 routes the agent: use swsd_get_catalog_item to inspect a single item's variables, then swsd_create_service_request to submit a request. This names the alternatives and the conditions for each, leaving nothing 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, idempotentHint and destructiveHint=false, so the safety profile is covered structurally. The description adds genuine context beyond the annotations by explaining the hierarchy model (parent_id links) and the shape of the return, though it says nothing about pagination limits or rate 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?

Three short sentences that are front-loaded: purpose, return/hierarchy, then usage. Each sentence carries distinct information with no 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?

With an output schema, rich annotations and fully documented parameters, the description only needs to establish purpose, hierarchy semantics and routing, all of which it does. 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% and the schema itself documents page, query and per_page with defaults and bounds. The description adds no parameter-level meaning beyond that, so 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?

States a specific verb (List) and resource (SWSD incident/solution categories), and adds scope detail by noting categories form a parent_id hierarchy. An agent can distinguish this from sibling list tools like swsd_list_incidents or swsd_search_solutions 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?

Gives an explicit, actionable when-to-use: 'Use this to validate category_name before swsd_create_incident or swsd_update_incident,' naming the exact downstream tools. It lacks when-not guidance or explicit alternatives for category lookup, but the positive routing is strong and specific.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read-only nature is covered. The description adds useful context by naming the fields returned and the validation workflow. However, it does not mention pagination behavior or rate limits, which would be valuable given the page/per_page params.

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, front-loaded with the action and resource, followed by the return fields and usage guidance. No waste.

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?

Complete enough for a simple list tool with a defined purpose. The only gap is pagination behavior, but the annotations already cover the safety profile and the output schema exists. The description does its job without needing to explain return values.

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 schema fully documents page, query, and per_page. The description adds no parameter-specific syntax or format details beyond what the schema provides. Baseline 3 is appropriate when the schema handles all 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?

States a specific verb+resource ('List SWSD departments') and parenthetically clarifies scope with 'organizational divisions', immediately distinguishing it from sibling list tools like swsd_list_groups or swsd_list_roles.

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 the use case: 'Use this to validate department_name before incident write tools.' This tells the agent exactly when to invoke this tool versus others, and ties it to a concrete workflow.

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 fully covered. The description's only added behavioral content is the returned field list, which the output schema already carries, so it adds little beyond the structured data.

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 tight sentences with the identity of the resource and its return shape front-loaded, followed by the use case. 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?

With an output schema present and annotations covering the safety profile, the description need not restate return values or safety. It covers purpose, scope and use case adequately; the only mild gap is scoping/alternatives against the many sibling list tools.

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 fully documented in the schema. The description adds no syntax or filtering detail beyond what the schema provides, making the baseline 3 the correct score.

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 (List) and resource (SWSD groups) and disambiguates the term with '(assignment teams)', which distinguishes it from sibling list tools like list_roles or list_users. It does not explicitly name a sibling the way the strongest definitions do, so 4 rather than 5.

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?

'Useful for understanding team structure when triaging tickets' gives a concrete usage context. It stops short of stating when NOT to use it or which alternative sibling tool to prefer, so it lands at clear-context-without-exclusions.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds the returned field list, but that overlaps the existing output schema and says nothing about pagination behavior, ordering, or result caps.

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

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

Two short sentences, zero filler, with the core purpose front-loaded and the alternative tool named second. Nothing repeated or padded.

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?

An output schema exists, so enumerating return fields is not required; the description still supplies it plus the sibling alternative. Remaining gaps (pagination/ordering semantics) are handled by the schema's page/per_page definitions, so completeness is only slightly short of ideal.

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%, including the non-obvious dual id/number auto-detection for incident_id and the page/per_page bounds, so the schema carries the parameter burden. The description adds no parameter-level meaning, making the baseline 3 correct.

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 (List) and resource (comments on a SWSD incident) and explicitly names the sibling mutating tool swsd_add_incident_comment, so the agent can distinguish read vs write without opening a 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 routes the agent to swsd_add_incident_comment when the intent is to add rather than read, giving a clear when-not alternative. It does not, however, address when to prefer this call over other incident reads such as swsd_get_incident.

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 cover read-only/idempotent/non-destructive semantics, so the bar is lower. The description adds genuine behavioral disclosure beyond them: it documents that assignee_email/requester_email are silently ignored server-side and applied client-side (with a verification date), and that results are compact summaries rather than full records.

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?

Front-loads purpose, then return shape, routing, and filter semantics in four dense sentences. Every sentence carries information, though the client-side NOTE is somewhat long and could be tightened.

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 19-parameter list tool with an output schema, it supplies what the structured fields cannot: return summary contents, server-vs-client filter behavior, OR semantics, and the follow-up tool for detail. Nothing an agent needs to invoke it correctly appears 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 meaning beyond the schema by explaining repeated-key array semantics (values within a filter are OR-ed) and by flagging the two email filters as client-side, which the schema alone does not convey.

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+resource ('List SWSD incidents') with explicit scope: structured filters, pagination, and compact summaries. It also distinguishes itself from the sibling swsd_get_incident by prescribing it for full detail, so an agent can route without opening schemas.

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 routes to swsd_get_incident for full row detail and clarifies which filters run server-side vs client-side, a real usage constraint. It does not, however, distinguish itself from swsd_list_my_incidents, leaving one sibling relationship implicit.

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, destructiveHint=false and openWorldHint, so the safety profile is fully covered without the description's help. The description adds the useful fact that sub-tasks are also reachable through swsd_get_incident long mode, but no auth, pagination, or ordering behavior is disclosed beyond that.

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, front-loaded with purpose, then alternatives. The middle sentence enumerates eight returned fields, which largely duplicates the output schema and is the only mildly wasteful element.

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 an output schema, full annotation coverage, and one fully documented parameter, the description only needs to establish purpose and routing, which it does. The field enumeration is redundant rather than additive, so the definition is complete but slightly over-specified in the wrong place.

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?

There is a single parameter with 100% schema description coverage, including the id-vs-number auto-detection rule, so the schema carries the full semantic load. The description adds nothing about incident_id; baseline 3 applies when the schema is complete and the description is silent on 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?

States a specific verb and resource ('List sub-tasks on a SWSD incident') with explicit scope, and names the sibling tools that create/complete those same sub-tasks, so an agent can place it precisely in the task-related cluster. The scope of 'sub-tasks belonging to one incident' separates it from the general incident listers.

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 routes the agent: swsd_create_incident_task for adding, swsd_update_task_state for completing, and it discloses that the same data is available inline via swsd_get_incident with detail_level "long" — a real alternative-path hint. There is no explicit condition saying when to prefer one route over the other, so it stops short of a full when/when-not statement.

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 read-only, idempotent, non-destructive, open-world, so the safety bar is covered. The description adds substantial behavior beyond that: it calls swsd_get_me first, applies server filters, then narrows client-side by assignee.email, and cites live verification of the API bug with a date. It stops short of stating the performance/latency cost of retrieving a large unfiltered tenant result set client-side.

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?

Front-loaded with the core purpose, then the implementation rationale and the alternative route. Dense but every sentence carries information; the only mild cost is length, with the verification-date parenthetical being slightly verbose for a description field.

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 an output schema present, return values need not be described, and annotations cover the safety profile. The description supplies the remaining critical context — the internal swsd_get_me dependency, the client-side filtering necessity, and the correct sibling for broader queries — so nothing an agent needs to invoke this 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 coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by disclosing that the schema's requester_email-style filters are silently ignored server-side (a fake email returns the entire tenant), which materially changes how the agent should read those parameters. It does not document the other 16 parameters, but it need not given full 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?

States a specific verb+resource+scope ('List incidents assigned to the authenticated user') and explicitly distinguishes itself from swsd_list_incidents. An agent can tell exactly what this returns and how it differs from the sibling without opening either 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?

Names the alternative and the condition that selects it: 'For broader queries use swsd_list_incidents with assigned_to=<group_id> (group filtering does work server-side).' It also warns that requester_email/assignee_email server-side filtering is broken, steering the agent away from an ineffective call pattern.

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, destructiveHint=false, openWorldHint=true, so safety behavior needs no restatement. The description adds real behavioral context: filters use SWSD repeated-key array semantics with OR within a filter, and results are compact summaries rather than full records. Disclosure of the OR semantics is genuinely non-obvious and useful.

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-loaded with purpose, then return shape and sibling routing, then filter semantics and usage context. No redundancy and nothing padded.

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 an output schema present, the description need not explain return values, yet it conveniently names the summary fields and points to swsd_get_problem for detail. Between annotations, the 100%-covered schema, and this text, an agent has everything needed to call 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 the baseline is 3. The description exceeds that by explaining the cross-parameter semantics that the schema does not: multiple values inside one filter key are OR-ed, which governs how state/priority/state_is_not arrays combine. It does not document pagination interaction beyond what the schema states.

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 ('List SWSD problems (ITIL problem records)') and immediately scopes it with structured filters plus pagination. It is clearly distinguishable from the sibling swsd_get_problem, which it explicitly names as the single-record alternative.

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?

Gives a concrete usage context ('when investigating recurring incidents or identifying root causes that span multiple tickets') and routes the agent to swsd_get_problem for full detail of a row. It stops short of stating exclusions (e.g. when to prefer a different list tool), but the alternative is named.

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, destructiveHint=false, so the safety profile is fully covered. The description adds the perception that roles are permission profiles and names return fields (id, name, description), but discloses no pagination behavior, result limits, or auth requirements beyond the structured data.

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, front-loaded with the core purpose, with no filler. Minor redundancy in restating return fields that the output schema already provides.

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 an output schema, complete annotations, and fully documented parameters, the remaining burden on the description is purpose plus usage, both of which are supplied. Only minor gaps (e.g., expected result volume) keep it from a 5.

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% (page, query, per_page all documented), so the schema carries full parameter semantics. The description never mentions the name-substring filter or pagination, adding no meaning beyond the schema; 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?

Specific verb+resource ('List SWSD roles') with a clarifying gloss '(permission profiles)' that removes ambiguity about what a role is in this API. It is clearly distinguishable from the incident/user/catalog list siblings, though it does not explicitly name or contrast a sibling.

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 a concrete when-to-use context: 'useful for understanding what users can do in SWSD when triaging permission-related tickets.' It gives clear context but no exclusions or explicit alternatives, so it falls just short of the top band.

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, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds value beyond that by listing the returned fields and framing the call as a pre-write validation step; it does not mention pagination limits, which is a minor omission given the page/per_page params.

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

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

Two short sentences, zero filler. Scope and return shape come first, and the actionable usage guidance is front-loaded at the end without 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?

A simple read-only list tool with full schema coverage, rich annotations, and an output schema, so return values need no prose. The description supplies the one thing structured data cannot: why and when to call it.

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 page, per_page, and query all documented in the schema itself including defaults and bounds. The description adds no parameter-level meaning (e.g., matching semantics of the query substring), so baseline 3 is correct.

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 ('List SWSD sites') and disambiguates the term with a parenthetical gloss ('physical office/branch locations'). It also enumerates the returned fields, making it clearly distinct from sibling list tools such as swsd_list_departments or swsd_list_groups.

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?

Gives an explicit use case: validating a site_name before calling incident write tools, which is exactly the kind of precondition an agent needs. It stops short of stating exclusions or naming an alternative lookup path, so it is clear but not fully prescriptive.

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, destructiveHint=false, and openWorldHint, so the safety profile is fully covered by structured data. The description adds only that results serve as work-log context; it says nothing new about pagination semantics (which the schema carries) or auth needs.

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 filler. The purpose is front-loaded and the usage cue follows immediately, with no redundant restatement 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?

With a rich output schema and full annotation coverage, the description is nearly self-sufficient. The only minor gap is that it never states the required object_type+id pairing for targeting a parent record, though the schema marks both as required.

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 four parameters (id, object_type, page, per_page) are already documented with ranges, defaults, and the enum. The description's enumeration of parent types echoes the object_type enum without adding new syntax or constraints, 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?

States a specific verb (List) and resource (SWSD time entries) plus the scope of parent object types it applies to (incident, problem, change, release). An agent can distinguish it from swsd_log_time and swsd_update_time_track, which mutate rather than read time entries.

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 tells the agent when to reach for it: 'before adding/updating time when you need existing work-log context.' That routes the agent away from the write-time siblings. It stops short of naming those siblings or stating exclusions, so it is not a full 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=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the returned field set and the assignment-relevance semantics, but nothing about pagination behavior or result volume beyond what the schema and output schema provide.

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

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

Three compact sentences, front-loaded with the action and return fields, followed by the two parameter-selection rules. No filler and every clause carries usable information.

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

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

For a read-only list tool with rich annotations, an output schema, and fully documented parameters, the description covers purpose, routing, and key parameter intent. It stops short of noting pagination defaults or that results are paged, which is a minor gap given the 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 description coverage is 100%, so the baseline is 3. The description adds intent-level meaning beyond the schema: `available_for_assignment_only` is framed as the way to find valid assignees, and `email` as an exact single-user lookup, which helps disambiguate it from the substring `query` parameter.

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+resource ('List SWSD users') and enumerates the returned fields, so an agent knows exactly what it retrieves. It is clearly distinguishable from sibling tools like swsd_list_incidents or swsd_list_sites.

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?

Gives explicit conditional guidance: set `available_for_assignment_only: true` to find valid assignees for swsd_assign_incident, and set `email` for an exact single-user lookup. This routes the agent toward correct parameter choices, though it states no explicit exclusions or when-not-to-use conditions.

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

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

Annotations already declare readOnlyHint=false and non-idempotent, so the write nature is partly redundant, but the description adds genuinely useful behavioral context beyond the structured fields: it honors SWSD_WRITE_MODE and does not retry on transient failure. That retry/write-mode disclosure is valuable for an agent deciding how to handle failures. It stops short of stating what gets returned or created.

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 the action, required inputs, and write/retry semantics all front-loaded. No waste 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 write tool with no output schema and 100% schema coverage, the description covers purpose, target object types, required params, and write-mode/retry behavior. It does not indicate what the call returns (e.g. a created time-track id), but that is a minor gap given the otherwise complete disclosure.

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 all four parameters are documented in the schema, so the description's listing of required fields adds little. The schema itself clarifies that minutes_parsed is the SWSD field name and that id is the parent record id, 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?

States a specific verb+resource ("Log time against a SWSD incident, problem, change, or release") and scopes the exact object types targeted. The verb "log" is clearly distinct from sibling read/update operations like swsd_list_time_tracks and swsd_update_time_track, so an agent can select it 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 implies when to use it (to log/append time entries against one of four parent object types) and enumerates every required parameter. However, it never contrasts this tool with the alternatives (e.g. swsd_update_time_track for modifying an existing entry), leaving that routing 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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: results are compact summaries with 240-char truncated excerpts, and the index is asynchronous with a freshness lag. The indexing caveat is a non-obvious trait that would otherwise cause an agent to wrongly conclude an article was never created.

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, front-loaded with the core action, then details, then the alternative and the caveat. Each sentence earns its place with no 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?

An output schema exists, so return-value explanation is optional, yet the description still notes the truncated-excerpt format. Combined with the freshness caveat and the routing to swsd_get_solution, nothing an agent needs to call this 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 documents all four parameters. The description restates the semantics of query and category, adding little beyond what the schema provides, and says nothing about the page/per_page pagination parameters. Baseline 3 applies when the schema does the heavy lifting.

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 ('Search SWSD knowledge-base solution articles') and immediately distinguishes itself from the sibling swsd_get_solution, which returns full bodies. An agent can tell exactly what this tool does and where it sits relative to its neighbors without opening a 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?

Explicitly covers the two usage modes (query for free-text, category for filtering), names the alternative tool for retrieving full bodies, and warns about the async indexing delay with a concrete workaround for verifying just-created articles. When-to-use, when-not (won't see fresh articles), and alternatives are all present.

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=false, destructive=true, idempotent=false and openWorld=true, so the bar is lower; the description still adds real value by disclosing that is_private is immutable here (delete + re-create required) and that the handler does not retry on transient failure — a non-obvious operational trait. It omits permission/auth requirements and any note about partial failure, keeping it below a 5.

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, front-loaded with the core action, then the caveat, then the write warning. The middle sentence enumerating the three parameters is mildly redundant with the schema but the rest earns its place. Nothing bloated.

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 3-parameter destructive mutation with no output schema, the description covers the essential gotchas an agent needs to call it correctly: which fields, what cannot be changed, and the retry caveat. Given annotations already carry the safety profile and the schema is fully documented, only minor gaps (permissions, subsequent-read guidance) remain.

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 the schema itself is unusually rich, documenting the id-vs-number auto-detection for incident_id, the replace semantics and the 50000-char cap for body. The description only restates the required parameter names, adding no syntax or format meaning beyond the schema. 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?

States a specific verb and resource ('Update the body of an existing SWSD incident comment') and immediately names the three inputs, which cleanly separates it from the sibling swsd_add_incident_comment (create) and the read-only swsd_list_incident_comments. An agent can distinguish it without opening any 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?

Gives clear context for the operation and an explicit when-not/alternative: visibility cannot be toggled here, so delete and re-create instead. It also flags the write-mode retry behavior. It stops short of explicitly routing to siblings for creating comments or stating prerequisites such as permission scope, so it is not a full 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?

Goes well beyond the annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=false): it discloses partial-update semantics ('Only fields you provide are sent — others stay as-is'), that it does not retry on transient failure, and that custom-field types like Multi_picklist/User are unsupported. This is exactly the kind of behavioral context annotations cannot convey.

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

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

Front-loaded with purpose, then alternative routing, then write/behavioral caveats, then parameter detail. Dense but every clause earns its place; slightly long, preventing a full 5.

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 destructive write tool with annotations present and no output schema, the description supplies the crucial missing context: partial-update behavior, non-retry on transient failure, and custom-field constraints. 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% and the nested schema already documents id auto-detection, custom_fields format, and Date/Dropdown/Checkbox value rules. The description largely restates these and repeats the 'call swsd_describe_custom_fields first' guidance already in the schema, so added value is marginal — baseline 3 is appropriate.

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

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

States a specific verb+resource ('Update an existing SWSD incident') and immediately distinguishes itself from siblings by naming swsd_update_incident_state, swsd_assign_incident, and swsd_add_incident_comment. An agent can tell exactly what this tool owns versus its neighbors.

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?

Explicit when-to-use-elsewhere routing: state transitions go to swsd_update_incident_state, assignments to swsd_assign_incident, comments to swsd_add_incident_comment. It also states the scope of a generic update (only provided fields are sent). Nothing is 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 destructiveHint=true, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely new behavioral context — 'WRITE — does not retry on transient failure' and the fact that state names are tenant-specific — which the annotations cannot express. It stops short of saying whether an invalid or illegal transition errors out or silently no-ops.

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?

Front-loaded with the core action and the wrapper rationale, and every sentence carries usable information. It loses a point for duplicating the common state-name list that already appears verbatim in 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?

For a two-parameter mutation with no output schema, the description covers the prerequisite, the alternative tool, retry behavior, and tenant-specificity of state names. It does not address what a failed or rejected transition returns, which is the main remaining 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 description coverage is 100%, so the schema already documents both id and state, including the auto-detection of id by digit count. The description largely repeats the schema's state-value list rather than adding new semantics, 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?

States a specific verb and resource (transition an SWSD incident to a new state) and explicitly distinguishes itself from the sibling swsd_update_incident by calling itself a safer, narrower wrapper. An agent can select this over the general update tool without opening either 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?

Gives an explicit prerequisite (call swsd_get_incident first to see the current state) and names the alternative it is meant to replace (swsd_update_incident) with the reason to prefer it. The when-to-use condition is concrete rather than implied.

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 write/idempotent/destructive/openWorld hints; the description adds real context beyond them by stating that re-applying the same value is a no-op and by naming the exact state transitions (Completed vs. New). It stops short of covering permission requirements, error behavior, or side effects on related task fields, so it is strong but not exhaustive.

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?

Front-loaded with the purpose and the key parameter mapping, then a routing note, then a terse write/idempotency tag. Four short units with no padding, though the trailing 'WRITE — idempotent' fragment is slightly clipped in style.

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 3-param mutation tool with no output schema, the description covers what changes, the idempotency contract, and the scope boundary against alternate state handling. Missing only peripheral detail such as auth prerequisites or failure modes.

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%, including the completed boolean-to-state mapping and the incident_id auto-detection rule, so the schema does the heavy lifting. The description restates the completed semantics ('revert to "New"') but adds no syntax or format detail the schema lacks; 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?

States a specific verb and resource: 'Mark a SWSD incident sub-task as complete or incomplete.' The phrase 'incident sub-task' scopes it precisely and separates it from the incident-level sibling swsd_update_incident_state without the agent needing to open either 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?

Explicitly defines the when ('the common done/not-done transition') and the when-not with a routing instruction ('For finer state control (e.g., "In Progress"), use the SWSD UI directly'). The alternative for out-of-scope cases is named, so nothing is 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 destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is partly covered. The description adds real value beyond them: it flags this as a WRITE, notes that it honors SWSD_WRITE_MODE, and warns it does not retry on transient failure — material operational context an agent needs. No mention of auth/permission needs or reversibility.

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 tight sentences: the mutation/scope statement is front-loaded, followed by the payload requirement and the write-mode caveat. No filler or repetition of schema fields.

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, destructive write with no output schema, the description covers the mutation nature, the required update fields, write-mode handling, and retry behavior. It omits permission/auth requirements and any note on partial failure, but is largely sufficient given the annotations.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the non-obvious constraint that name and/or minutes_parsed must be passed (the schema's required list only covers object_type, id, time_track_id), clarifying the real minimum payload.

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 ('Update an existing SWSD time entry') and names the four parent object types it applies to, which cleanly separates it from sibling writers like swsd_log_time and readers like swsd_list_time_tracks. It stops short of explicitly naming those siblings, so it lands at 4 rather than 5.

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?

'Pass name and/or minutes_parsed' tells the agent what to supply for a meaningful update, which is genuinely useful invocation guidance. However, there is no explicit when-to-use vs. when-not, and no pointer to swsd_log_time for creating new entries, so usage is only implied.

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=false and destructiveHint=false, and the description adds meaningful context beyond them: 'WRITE — honors SWSD_WRITE_MODE', which tells the agent the operation is gated by a write-mode setting. It does not disclose failure modes, size ceilings, or whether re-uploading duplicates the attachment, but the write-mode signal is real added value.

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 compact sentences, front-loaded with purpose and then the input-selection rule. No filler, no repetition 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?

For a write tool with annotations covering the safety profile and no output schema, the description covers the essentials: what it attaches to, which input field to use per transport, and the write-mode gate. It omits return value expectations and any size/format limits, but these are largely inferable from the schema constraints.

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 five parameters are already documented. The description's transport guidance for content_base64 vs file_path largely restates the schema's own wording, adding little beyond the baseline expected when the schema does the heavy lifting.

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) plus the resource (attachment) and enumerates every valid parent type, so the agent knows exactly what the tool operates on. No sibling tool performs uploads, so differentiation is implicit but 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 conditional guidance on which input to use (content_base64 for hosted/HTTP, file_path only on stdio), which is genuinely useful context. However, it gives no when-to-use vs when-not guidance relative to alternatives, nor prerequisites such as required permissions on the parent record.

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