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

With no annotations provided, the description carries the full burden. It explicitly states that this tool changes the ticket, which is a behavioral disclosure. It also mentions that actions vary per ticket/user/state, implying context-dependence. However, it does not detail side effects like whether steps are immutable or if there are irreversible actions, but given the existence of an output schema, this is acceptable.

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

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

The description is three sentences, each with a purpose. It front-loads the main purpose, then adds a crucial prerequisite warning, and concludes with a safety note. No wasted words. The structure is ideal for an MCP description.

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

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

Given the tool's complexity (8 parameters, no schema descriptions, no annotations), the description provides essential usage guidance. The presence of an output schema helps with return value understanding. The main gap is the lack of parameter explanations, but the tool's purpose and behavior are sufficiently outlined for an agent to understand when and how to use it, particularly with the hint to list actions first.

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 0%, so the description must compensate. It mentions 'text', 'attachments', 'step_fields', etc. only indirectly by saying 'answering, closing, escalating', but does not explain specific parameters like 'action_arguments' or 'ticket_fields'. The description adds context for action_id and ticket_id (validity and prerequisite), but for other parameters it relies on the schema which has no descriptions. Since 8 parameters that are mostly undocumented, the description could do more to explain how to use them.

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

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

The description clearly states the tool's purpose: 'Apply a ticket action to an existing ticket - answering, closing, escalating and so on - and return the id of the new editing step.' It uses specific verbs (apply, return) and names the resource (ticket). It also distinguishes from siblings by focusing on actions, while siblings like list_ticket_actions and get_ticket handle listing and retrieval.

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

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

The description provides explicit guidance: 'Call list_ticket_actions first: only the ids listed there are valid, and they differ per ticket, user and state.' This tells the agent the prerequisite step and warns about validity constraints. It also says to confirm with the user when intent is ambiguous, which is excellent for ambiguous situations.

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?

With no annotations provided, the description must carry the full burden. It states the return value (id) and warns about rejection of unknown ticket_fields versus silent ignoring of action_arguments, which is useful. However, it does not disclose whether the operation is destructive, if it requires authentication, or if there are rate limits, leaving gaps.

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

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

The description is concise at two sentences, immediately stating the core purpose. It front-loads the primary behavior and return value, then adds parameter notes. One minor improvement could be to structure the parameter notes more clearly, but overall it is efficient.

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

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

Given the tool has 6 parameters, 0% schema coverage, and no annotations, the description covers only a subset of parameters (text, ticket_fields, action_arguments) and lacks details on attachments, owner_guid, and html_content. The presence of an output schema helps but does not fully compensate for missing parameter explanations.

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 0%, so the description must compensate. It explains the critical `text` parameter and adds meaning to `ticket_fields` and `action_arguments` by noting their optionality and server behavior. However, `owner_guid`, `attachments`, and `html_content` are not described, leaving some parameters without context.

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

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

The description clearly states the tool creates a new ticket and returns its ID. It distinguishes itself from sibling tools like search_tickets, get_ticket, and apply_ticket_action by focusing on creation, not retrieval or modification.

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 mentions that `ticket_fields` and `action_arguments` are optional and only for advanced cases, and notes that unknown fields are rejected while unknown arguments are ignored. However, it does not provide guidance on when to use this tool versus alternatives like apply_ticket_action, or when attachments or html_content should be used.

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?

With no annotations, the description carries full burden. It explicitly states the tool is read-only ('Read one ticket') and warns that the full record can be large and may contain personal data. This adds behavioral context beyond what structured data provides. It does not mention authentication, error handling, or idempotency, but the core safety trait is transparent.

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

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

The description is two sentences with no wasted words. The first sentence front-loads the core purpose, and the second adds a practical usage tip. Every sentence earns its place.

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

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

Given the tool's simplicity (2 parameters, output schema present), the description covers the core action, a key parameter hint, and a data sensitivity warning. It does not discuss error behavior or edge cases, but the output schema fills return value details. The description is sufficient for an agent to use the tool correctly in most scenarios.

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 0%, so the description must compensate. It explains the `fields` parameter's purpose (limit response, avoid large/personal data) and why it is useful. The `ticket_id` parameter is not explained in text, but its purpose is obvious from name and context. The description adds meaningful value beyond the bare schema.

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

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

The description clearly states the verb 'Read' and the resource 'one ticket with its fields and attributes'. It distinguishes itself from sibling tools like 'search_tickets' (multiple results) and 'create_ticket' (write) by specifying a single ticket retrieval. The purpose is specific and unambiguous.

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

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

The description provides a usage hint to pass the `fields` parameter to limit response size and avoid personal data, which is helpful. However, it does not explicitly state when to use this tool versus alternatives (e.g., 'search_tickets' for filtering, 'list_ticket_actions' for operations). The guidance is implied but lacks exclusions or comparisons.

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?

No annotations are provided, so the description must fully disclose behavior. It states it's a read operation ('Read'), but does not mention idempotency, rate limits, or whether the step is returned in a specific format. It hints at field filtering but lacks detail on what 'applied ticket action' means or if the action is mutable.

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

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

The description is two sentences long with no wasted words. It front-loads the purpose ('Read one editing step...') and adds a helpful optimization hint ('Pass fields to reduce...'). Every sentence earns its place.

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

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

The tool has a rich output schema (mentioned in context), so the description does not need to detail return values. It covers the key behavior (reading a step, including text and action) and parameter usage. No mention of error states or prerequisites, which is a minor gap for a complex tool with many siblings.

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 0%, so the description must compensate. It explains the 'fields' parameter by saying 'Pass fields to reduce the returned fields and attributes', giving context not in the schema. However, it does not describe ticket_id and step_id beyond their names, which are clear from context.

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

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

The description clearly states 'Read one editing step of a ticket', specifying the verb 'read' and the resource 'editing step' with the scope 'of a ticket'. This distinguishes it from siblings like list_ticket_steps (list) and get_ticket (different resource).

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 this is for reading a single step, but does not explicitly say when to use it over siblings (e.g., get_ticket for ticket-level info, list_ticket_steps for multiple steps). No alternatives or exclusions are mentioned, so it's adequate but lacking guidance.

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

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

With no annotations provided, the description carries full burden. It mentions the action list is scoped to the authenticated user and returns a map, but omits details about permissions requirements, error conditions (e.g., invalid ticket_id), or whether the list could be empty.

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, no filler. The first sentence states the core purpose, the second links to a related sibling. Every word earns its place.

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

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

For a simple list tool with one parameter and an output schema, the description covers the output format and workflow integration. It is nearly complete but lacks parameter documentation, which is a minor gap given the tool's simplicity.

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

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

The input schema has a required ticket_id with no description (0% schema coverage). The description does not elaborate on ticket_id format, source, or constraints, leaving the agent with no additional guidance beyond the schema.

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

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

The description clearly states the tool lists ticket actions the authenticated user may apply, returning a map of id to display name. It distinguishes from sibling apply_ticket_action by noting the ids are its input.

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

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

The description implies usage as a precursor to apply_ticket_action, providing a natural workflow. However, it does not explicitly state when to use this tool over siblings like list_ticket_steps or get_ticket, nor does it mention exclusion criteria.

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

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

Annotations are absent, so the description carries the full burden. It discloses that for primary tickets in a bundle, steps from secondary tickets are merged, which is a key behavioral trait. However, it does not mention other important traits such as pagination, rate limits, data freshness, or what happens on error, which would be valuable for a history endpoint.

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

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

The description is two sentences long and front-loads the main purpose. It includes a behavioral detail (merged steps) and a sibling reference. Every sentence adds value, and there is no fluff. It could be slightly more structured (e.g., separate section for parameters) but is already efficient.

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

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

Given that the tool has an output schema (which explains return values) and only 2 simple parameters, the description does not need to cover return structure. It explains the bundle merging behavior and the sibling context. It might be slightly incomplete for agents needing to know about pagination or limits, but for a list endpoint with an output schema, it's largely sufficient.

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

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

Schema description coverage is 0%, so the description must compensate. However, the description does not explain either parameter (since or ticket_id). The since parameter especially benefits from explanation (e.g., format or semantics). The ticket_id is somewhat self-explanatory but formal guidance is missing. Baseline for 0% coverage would be lower, but with only 2 params and one being clear from the property name, a 3 is appropriate.

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

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

The description clearly states the tool lists 'editing steps (history) of a ticket' which is a specific verb+resource. It further distinguishes from siblings by mentioning behavior for bundle tickets and explicitly referencing the sibling `get_ticket_step` for single step retrieval, making it easy for an agent to differentiate.

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

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

The description provides clear context on when to use this tool (to list the entire step history) and when to use an alternative ('Use get_ticket_step for the text of a single step'). It doesn't explicitly say when not to use it or mention prerequisites, but the guidance on bundle tickets and the sibling reference is helpful.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns matching ticket IDs plus suggestions and that it uses a specific syntax. However, it does not mention behavioral traits like pagination, rate limits, or whether the operation is read-only, though the search nature implies safety.

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 consists of two concise sentences. The first explains functionality and syntax, the second explains the return value. No unnecessary words are present.

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

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

The description covers the main functionality and return value, and an output schema exists. However, it lacks explanation of the pagination parameters (limit, start) which are important for a search tool. Overall, it is reasonably complete but has a notable 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?

With 0% schema description coverage, the description must compensate. It adds meaning for the query parameter by explaining the syntax and providing examples, but it does not describe the limit, start, or locale parameters at all. This is insufficient for a 4-parameter tool.

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

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

The description clearly states that the tool searches tickets using a specific phrase syntax, with examples like 'printer' or 'Resource:"First Level Support"'. It distinguishes the search action from sibling tools such as create_ticket or get_ticket by its purpose and return value.

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

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

The description provides usage guidance by referencing the Tickets application's syntax, but it does not explicitly state when to use this tool versus alternatives or when not to use it. The context is implied but not formalized.

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?

No annotations are provided, so the description must convey behavioral traits. It clearly discloses the tool is read-only (reports/verifies) and connects it to server config and credential validation. It could be slightly improved by explicitly stating it has no side effects (like creating or modifying data), but the intent is clear enough from context.

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

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

The description is two sentences, front-loaded with the core purpose, and contains no extraneous information. Every sentence earns its place.

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

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

Given that the tool has zero parameters, an output schema exists (so return values are documented elsewhere), and the sibling tools all focus on tickets, this description is complete. It explains what the tool does, when to use it, and implies what it does not do (mutations).

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

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

The input schema has zero parameters and schema description coverage is 100% (trivially). The description adds meaning by explaining what the tool does with those zero parameters: it reports configuration and verifies connectivity. This is a case where the parameter semantics is inherently simple, and the description captures the purpose well.

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

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

The description uses a specific verb and resource: 'Report how this MCP server is configured and verify that the i-net HelpDesk can be reached with the current credentials.' It clearly distinguishes from sibling tools: all siblings deal with ticket operations, while this tool is about server and authentication status.

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

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

The description explicitly states when to use this tool: 'Use this first when a call fails with an authentication or connection error.' This gives clear guidance on the context and problem type that should trigger its invocation, and by omission implies it is not needed for normal ticket operations.

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