Gorelo MCP by usefulapi

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

Beyond the sparse annotations (only destructiveHint=true), the description discloses two behaviors an agent could not infer: that public comments may be emailed to the client, and that retrying after an unclear error can double-post. Those are exactly the side-effect and idempotency hazards that matter for a write call.

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 with zero filler: operation and mode first, then the semantic distinction, then the safety rule. The endpoint line is the only borderline element but is compact and additive rather than redundant.

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 write tool with no output schema and minimal annotations, the description covers everything an agent needs to call it correctly: thread scope, visibility semantics, HTML-ish body handling via the schema, and the retry hazard.

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 carries the field documentation and 3 would be the baseline. The description earns above-baseline credit by explaining the real consequence of the visibility parameter — a public reply is client-visible and may be emailed — which is not in the schema's terse "public = visible to the client".

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

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

The description opens with a specific verb and resource — "WRITE: add a comment to a ticket's main thread" — and the thread scoping distinguishes it from gorelo_create_ticket. It also names the transport (POST /v1/tickets/{ticketId}/comments), leaving no ambiguity about what operation is performed.

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 usage context: use public vs private depending on whether the client should see the comment, and a concrete operational rule (do not retry on unclear errors). It doesn't explicitly name a sibling alternative such as gorelo_list_ticket_comments for reading, so it stops short of full when/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?

Beyond the annotation, it discloses that this is a write operation, that an email side effect is opt-in via send_created_email (default false), and the underlying endpoint. It does not say what happens on partial failure or whether the created ticket is returned, 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?

Three short sentences, front-loaded with the write action and the required ids, with no filler. Every clause carries operational 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 14-parameter creation tool it covers the required fields and the notable email side effect well. However, with no output schema and no statement about what the call returns (e.g., the new ticket id), the agent lacks a key piece of context for chaining to gorelo_get_ticket or gorelo_add_ticket_comment.

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 description adds meaning for four parameters (the three required ids and the email flag), including a conditional rule for when to set send_created_email that the schema does not express. With 64% schema coverage and 14 parameters, remaining fields like client_id, contact_id, and description are left to the schema alone.

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 'WRITE: create a service ticket', a specific verb plus resource, and the verb distinguishes it from siblings like gorelo_list_tickets, gorelo_get_ticket, and gorelo_update_ticket. The POST /v1/tickets endpoint reinforces the create semantics.

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 explicit prerequisites for the required identifiers and names the exact lookup tools (gorelo_list_ticket_statuses, gorelo_list_groups, gorelo_list_ticket_types), which is actionable guidance. It does not state when to prefer gorelo_update_ticket or gorelo_add_ticket_comment instead, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, so the read-only safety profile needs no restating. The description adds only the raw REST endpoint path; it says nothing about behavior on a missing/invalid guid, whether the record is returned as a single object, or what fields come back (there is no output schema to cover 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?

Two short sentences, front-loaded with the operation and then the backing endpoint. No filler, nothing redundant.

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 single-parameter read-by-id tool with full schema coverage and readOnly annotations, the definition gives enough to invoke it correctly. The only gap is that no output schema exists and the description does not sketch what a device record contains.

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 parameter is documented in the schema as a guid sourced from gorelo_list_agent_assets. The description's 'by id (guid)' merely echoes that, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb plus resource ('Get one managed device by id (guid)') and is immediately distinguishable from the list-style sibling gorelo_list_agent_assets. It does not name that sibling directly in the description text, but the singular 'one' makes the fetch-by-id intent 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?

Usage is only implied: you call this when you already hold a device guid. The description gives no explicit when-to-use/when-not guidance and does not mention the sibling that produces ids (though the schema's param description points to gorelo_list_agent_assets). Adequate but with a clear gap.

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?

readOnlyHint=true already establishes the safety profile, so the description's job is additive context. It adds the scope of returned data and the underlying REST endpoint, but says nothing about permissions, whether hardware may be stale/missing for offline devices, or response shape.

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 substantive description of what is returned front-loaded before the API reference.

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 single-parameter read tool with no output schema, the description adequately conveys both the input identity and the nature of the result. A note on behavior for devices with unavailable hardware data would push it higher.

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 the single parameter is already documented as an agent asset GUID. The description adds only the placement of that id in the API path (/v1/assets/agents/{agentAssetId}/hardware), which is marginal value.

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

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

Uses a specific verb plus resource and enumerates the returned data (processors, memory, disks), which distinguishes it from gorelo_get_agent_asset or the list endpoints. It does not explicitly name a sibling to use instead, so it stops 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?

Implicit guidance only: an agent can infer this is the tool for hardware detail on a known device. There is no statement of when to prefer it over gorelo_get_agent_asset or the list tools, and no prerequisites (e.g., needing the asset id from a list call) are 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?

The readOnlyHint annotation already establishes this is a safe read, and the description is consistent with it by naming a GET endpoint. It adds no further behavioral context such as behavior on an unknown id, permission requirements, or response shape.

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 operation front-loaded and the endpoint path as compact supporting detail.

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 full schema coverage and a readOnlyHint, the definition covers what is needed to invoke it correctly. The only minor gap is that no output schema exists and the description says nothing about what an alert record contains.

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 single alert_id parameter is fully documented, including that it is a guid sourced from gorelo_list_alerts. The description only restates the guid format and adds nothing 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?

States a specific verb and resource ('Get one alert by id (guid)') and even cites the underlying endpoint, so the agent knows this is a single-record fetch. It does not explicitly name gorelo_list_alerts as the alternative, but 'one alert' versus a list tool is clear enough in context.

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

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

Usage is implied: use when you already have an alert id and need that record. There is no explicit statement of when not to use it or which sibling to pick (e.g., gorelo_list_alerts to find ids), so guidance is inferred rather than 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 readOnlyHint=true, so safety is covered. The description adds the upstream endpoint (GET /v1/clients/{clientId}), which helps correlate with API docs, but says nothing about error behavior for missing ids or response shape.

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, front-loaded sentences with no padding. The endpoint sentence is mildly redundant with the tool name but earns its place by anchoring to the underlying API.

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 single-parameter read tool with full schema coverage and a readOnly annotation, almost nothing is missing. Only the absence of guidance on missing/invalid ids keeps it from being fully complete.

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

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

Schema coverage is 100%, and the schema itself documents client_id including its provenance ('from gorelo_list_clients'). The description adds no meaning beyond that, which is the expected baseline when the schema carries parameter detail.

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 one client by id with its details'), which an agent can distinguish from gorelo_list_clients without opening either schema. The sibling is not named explicitly, so it falls short of full differentiation.

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 'one client by id' framing implies single-record retrieval versus the list sibling, but there is no explicit statement of when to use this over gorelo_list_clients or what to do if the id is unknown.

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, so the safety profile is covered. The description adds the underlying REST endpoint, which is mildly useful for developers but adds little behavioral context such as error behavior when the id is unknown.

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, front-loaded with the action and with zero redundant prose. 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 one-parameter read tool with readOnlyHint annotations, this is nearly sufficient; only the returned contact shape is unstated, which is a modest gap since no output schema exists.

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 explains the id comes from gorelo_list_contacts, so the description's 'by id' adds no new meaning. 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 ('Get one contact by id'), which clearly signals a single-record fetch distinct from the sibling gorelo_list_contacts. It does not explicitly name the list counterpart as an alternative, 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?

Usage is only implied: fetch a single contact when you have its id, otherwise presumably use gorelo_list_contacts. No explicit when-to-use/when-not guidance or alternatives are 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?

readOnlyHint=true is consistent with a GET. The description adds real behavioral value beyond annotations by disclosing that the response embeds line items and attachments rather than returning a bare invoice record — important since there is no output schema. It doesn't cover not-found or error behavior, which keeps 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?

Two sentences, zero waste, with the payload contents front-loaded before the endpoint detail. Nothing could be removed without losing 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 single-parameter read tool with a readOnly annotation and no output schema, the description covers what is returned (invoice plus line items and attachments) and how to address it. Only the absence of error/empty-result behavior keeps it from full marks.

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 the schema already explains that invoice_id comes from gorelo_list_invoices. The description adds no format, constraint, or sourcing detail beyond that, 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 ("Get one invoice") and adds scope detail by naming what comes back: line items and attachments. This implicitly separates it from gorelo_list_invoices, though it never names that sibling explicitly.

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

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

Usage is only implied — an agent can infer this is the single-record fetch and that the id comes from gorelo_list_invoices, but only because the schema says so. The description itself gives no when-to-use or when-not-to-use guidance relative to the list 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds the underlying endpoint (GET /v1/tickets/{ticketId}), which is mildly useful for orientation, but says nothing about what is returned, error behavior for unknown ids, or auth requirements.

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, no filler, with the core action front-loaded before the endpoint detail. Appropriately sized for a simple single-record getter, though the endpoint clause is of marginal value to an agent that cannot call REST directly.

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-only lookup with full schema coverage and a readOnlyHint annotation, the description provides everything needed to invoke it correctly. The absence of a description of the returned ticket fields is a minor gap given no output schema exists.

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 parameter already documents the uuid format and its origin in gorelo_list_tickets. The description only restates the type hint, adding no format or sourcing 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 ('Get one ticket by id') and pins the identifier format as uuid, which cleanly separates it from gorelo_list_tickets. It stops short of naming the sibling alternatives explicitly, but the 'one ticket by id' framing makes the retrieval-vs-list distinction 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?

Usage is implied rather than stated: an agent can infer this is the single-record fetch counterpart to the list tool, and the schema note 'from gorelo_list_tickets' supplies the id source. There is no explicit when-to-use/when-not statement or discussion of alternatives in the description itself.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the underlying endpoint (GET /v1/assets/agents) and the surfaced fields (status, OS, client), but says nothing about pagination behavior, default ordering, or result size limits beyond what the schema's cursor/page_size descriptions already imply.

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 with the resource description front-loaded and the API path appended as reference. Nothing is wasted or repeated.

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 six-parameter, all-optional read-only list tool with full schema coverage and no output schema, the description gives enough to call it correctly. A brief note on default result ordering or pagination expectations would close 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 all six optional parameters are documented in the schema, including enum-ish status ids and pagination cursors. The description adds no parameter-level meaning beyond that, 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 agent (RMM managed device) assets') and clarifies what an 'agent asset' is, which implicitly separates it from gorelo_list_custom_assets, gorelo_get_agent_asset and gorelo_list_agent_pending_updates. It does not explicitly name any sibling, so it falls just 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?

Usage is only implied: an agent can infer it should call this to enumerate devices and apply the query/client/status/updated_since filters. There is no explicit statement of when to prefer this over gorelo_list_custom_assets or when to switch to gorelo_get_agent_asset for a single device.

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?

readOnlyHint=true already covers the safety profile, so the description's value-add is the disclosure that no new scan is triggered and the data reflects the last scan — a real behavioral trait an agent would otherwise have to guess. It stops short of covering permissions, pagination, or result freshness/staleness semantics, 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?

One front-loaded sentence states the resource and scope, the parenthetical adds the key behavioral caveat inline, and the API endpoint is appended as reference. No filler and nothing buried.

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 single-parameter read tool with no output schema, the description is nearly sufficient: purpose, scope, and the no-rescan behavior are all present. What's missing is any hint of the returned patch fields or result volume/pagination, which an agent cannot get from structured data since no output schema exists.

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 a single documented 'agent_asset_id' guid parameter, so the schema carries the semantics. The description only adds 'managed device' framing and the API path, which restates rather than extends what the schema already says.

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 the Windows updates pending on a managed device') with explicit scope, plus the underlying API path. No sibling tool covers patches or pending updates, so there is zero overlap ambiguity with the rest of the catalog.

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 parenthetical '(no new scan starts)' implicitly signals when this is appropriate — cheap read of cached last-scan data — which gives the agent a real usage cue. However, it never states when NOT to use it, what to do if data is stale, or what alternative exists for triggering a fresh scan, so guidance is only implied.

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

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

readOnlyHint=true already establishes this is a safe read, so the burden is low. The description contributes the default sort direction ('newest first'), but says nothing about pagination behavior despite a cursor parameter, nor about result size limits beyond what the schema states.

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, front-loaded sentences with no filler. The trailing 'API: GET /v1/alerts' is mildly useful for traceability but consumes space without helping an agent decide or invoke.

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 9 optional parameters, no output schema, and cursor-based pagination, the description should at least indicate the paginated return shape and how to page through results. It leaves that entirely to the schema's cursor description, which is workable but incomplete for a listing tool.

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 89%, so nearly every parameter is already documented in the schema; the description only echoes the default ordering with 'newest first'. It adds no deeper semantics such as how status_ids interacts with type_ids or whether filters are ANDed.

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 alerts') and enumerates the alert kinds (uptime, script, external). It is distinguishable from the singular sibling gorelo_get_alert by the verb, though it never explicitly says it returns a collection of many alerts.

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?

No guidance on when to use this versus gorelo_get_alert or gorelo_update_alert_status, and no mention of how filters like type_ids or status_ids should drive a decision. The only hint is the implied 'list' semantics and the default newest-first ordering.

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, so the safety profile is covered. The description adds the underlying endpoint (GET /v1/clients/{clientId}/locations), which aids transparency about the data source, but says nothing about return shape, empty results, or pagination.

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 with the scope stated first and the endpoint second; nothing redundant 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?

For a simple single-parameter read-only list with no output schema, the description covers what the tool returns conceptually (locations of one client) and the endpoint. Only minor gaps remain around result ordering/pagination, which are low-stakes here.

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% for the single client_id parameter, so the schema already documents it. The description only restates that the list is scoped to one client, adding no format or validation details beyond the schema, which matches the baseline 3.

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 (locations/sites) explicitly scoped to one client, which distinguishes it from the unrelated gorelo_list_clients and other list_* siblings. The parenthetical '(sites)' usefully disambiguates the term 'locations'.

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

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

Usage is implied — 'of one client' signals you must target a specific client — but there is no explicit when-to-use guidance or named alternative (e.g., how this differs from gorelo_list_clients or gorelo_get_client). An agent can infer intent but not the routing 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?

The readOnlyHint annotation already declares this is a safe read. The description adds the underlying endpoint (GET /v1/clients), which is mildly useful, but says nothing about paging through results, result ordering, or what a client record looks like — and no output schema exists to cover 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 short sentences, front-loaded with purpose and the usage hint, then the endpoint. Nothing is redundant 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?

Annotations and schema together cover safety and inputs, but with no output schema the description never explains the response shape or how to page using the cursor. For an entry-point list tool with seven parameters, that is a noticeable gap but not a blocking one.

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

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

Schema coverage is 100%, so all seven parameters (query, cursor, group_ids, page_size, status_ids, created_since, updated_since) are fully documented in the schema. The description adds no parameter meaning beyond that, which is the baseline case for complete 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 and resource: 'List the MSP's clients (customers)'. It is clearly a list operation and distinct from gorelo_get_client, though the difference is only implied by the phrase 'find a client id' rather than stated outright.

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?

'Good first call to find a client id' gives real context on when to reach for this tool before the id-based tools like gorelo_get_client or gorelo_list_invoices. It does not name an alternative or an exclusion, so it falls just short of a 5.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context — and it adds essentially none beyond the HTTP endpoint (GET /v1/contacts). It says nothing about ordering, default filters, whether the list is scoped to the caller's tenant, or how paging results are returned.

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 with the purpose front-loaded; nothing is buried. The trailing "API: GET /v1/contacts" is marginal value for an agent but is not verbose enough to be a real cost.

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

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

The tool is a simple filtered list with a fully documented schema and a read-only annotation, and pagination is covered by the cursor parameter, so the essentials are present. What is missing is any statement of filtering semantics (e.g. how client_ids/status_ids/location_ids combine) and any mention of result shape, which for a tool with no output schema would be worth a sentence.

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 documents every parameter including the cursor's origin (DataContext.Pagination.NextCursor) and the 1-200 page_size range. The description adds no additional meaning, 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 and resource ("List client contacts") and disambiguates the resource by glossing it as "end users", which separates it from the sibling list_clients and get_user tools. It does not explicitly contrast with gorelo_get_contact (single-record fetch), but the verb alone makes the distinction legible.

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

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

The description gives no when-to-use guidance, no prerequisites, and never names an alternative such as gorelo_get_contact for a single lookup or gorelo_list_clients for the parent entity. Usage is only inferable from the verb "List".

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds that results include service lines (a return-content hint, valuable since there is no output schema) and the endpoint path, but says nothing about pagination behavior, rate limits, or result ordering.

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 with zero waste; the resource and return scope are front-loaded, and the endpoint is a compact secondary detail. Nothing is repeated from the schema or annotations.

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

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

With all parameters documented, readOnlyHint covering safety, and no output schema to explain, the description is nearly sufficient. The note that service lines are included covers the main return-value expectation, though pagination flow is left entirely to the 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 five parameters (query, cursor, page_size, client_ids, status_ids) documented inline, so the baseline is 3. The description contributes no additional parameter meaning such as filter combination semantics or match behavior.

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 pairs a specific verb ('List') with a precise resource ('billing contracts with their service lines') and names the underlying endpoint. This distinguishes it cleanly from siblings like gorelo_list_invoices or gorelo_list_clients, though it does not explicitly contrast with those alternatives in text.

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?

There is no when-to-use, when-not-to-use, or alternative-routing guidance. An agent must infer from the name and siblings that this lists contracts rather than invoices or tickets, with nothing in the description to confirm that 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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds scope (custom assets only) and identifies the underlying endpoint, but says nothing about pagination behavior despite cursor/page_size being exposed. Adequate, not rich.

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, front-loaded with scope and followed by the endpoint. Nothing redundant and no wasted preamble.

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, no-required-param list tool with a fully described schema and no output schema, the description covers purpose and scope sufficiently. The main remaining gap is pagination/return-shape expectations, which the annotation and schema partially absorb.

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

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

Schema description coverage is 100%, so every parameter including query, cursor, page_size, client_ids and updated_since is already documented. The description adds no parameter meaning beyond the schema, which is the expected baseline 3 here.

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 custom (non-agent) assets') and distinguishes itself from the agent-asset listing by the '(non-agent)' qualifier. Concrete examples (printers, switches, licences) sharpen what counts as a custom asset. It doesn't name gorelo_list_agent_assets explicitly, so differentiation is implied rather than stated.

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

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

Usage is only implied by the examples and the '(non-agent)' qualifier; there is no explicit when-to-use or when-not-to-use guidance and no pointer to the sibling list_agent_assets as the alternative. An agent can infer intent but must reason about it.

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?

readOnlyHint=true already establishes the safety profile, and the description adds the underlying endpoint (GET /v1/organization/groups). However it says nothing about what comes back — no pagination behavior, no indication of whether the payload is a bare id/name list or richer group objects — which matters more here since there is no output schema.

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

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

Two short clauses, purpose first, call-condition second, endpoint last — nothing redundant and nothing buried. Every element 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 zero-param read-only list tool with readOnlyHint set and no output schema, the description covers what it does, why to call it, and the backing endpoint. The only meaningful omission is the shape of the returned group records, which an agent must discover at call time.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. The omission of any parameter discussion is appropriate rather than a gap.

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?

Names a specific verb and resource ("List technician groups") that distinguishes it from sibling list tools such as gorelo_list_users or gorelo_list_clients. The parenthetical adds the reason the list matters (ids for ticket creation), though it doesn't state how groups differ in scope from users.

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

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

"ids are needed to create a ticket" gives a concrete call condition that ties this tool to gorelo_create_ticket. It stops short of naming an explicit alternative or exclusion, but the practical when-to-use is clear.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the description's job is lighter. It adds that results include status, totals and client and names the backing endpoint (GET /v1/invoices), but says nothing about pagination behavior, default page size, or result ordering.

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 padding, with the resource and return fields front-loaded before the endpoint reference. Nothing could be removed without losing content.

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

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

For a read-only list tool with full annotation safety coverage and no output schema, the description gives enough to call it: resource, return fields, endpoint. The main residual gap is pagination guidance, though the cursor and page_size params cover it structurally.

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 82%, so the schema already explains cursor, page_size, query and the date filters. The description contributes no additional parameter meaning; a brief note that filters combine (e.g. status_ids + due_date_before) would have added value.

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

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

States a specific verb and resource ("List invoices") and adds what the rows carry (status, totals, client). It does not distinguish itself from the sibling gorelo_get_invoice (single-record fetch), leaving that routing to inference.

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?

No statement of when to use this versus gorelo_get_invoice or gorelo_list_contracts, no prerequisites, no exclusions. The only usage-adjacent hint ("find overdue invoices") lives in the schema for due_date_before, not in the description.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower; the description contributes the underlying HTTP endpoint (GET /v1/projects) and notes the fields each project carries. It says nothing about default sort order, pagination limits, or total-count behaviour, which are the remaining behavioural unknowns for a cursor-paginated list.

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, front-loaded sentences with no padding. The second sentence ("API: GET /v1/projects") is mostly implementation trivia for an MCP caller, so it does not fully earn its place, but the description is far from 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?

With 8 optional parameters, no output schema and only a read-only annotation, the description should clarify default ordering and how the filter parameters interact; it only mentions included fields. Minimum viable for a simple list tool, but leaves real gaps.

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 88%, so all meaningful parameters (query, cursor, sort_by, page_size, client_ids, status_ids, updated_since) are already documented in the schema. The description adds no extra semantics such as how filters combine or what the default sort is, 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+resource ("List projects") and adds that each project carries status, client and lead, which differentiates it from gorelo_list_project_tasks and gorelo_list_clients. It does not explicitly name a sibling for contrast, so it stops 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?

There is no statement of when to use this tool rather than a sibling (e.g. gorelo_list_project_tasks for tasks, gorelo_get_client for client detail), nor any prerequisites or exclusions. Usage must be inferred entirely from the name and the parameter list.

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?

readOnlyHint=true already declares the safety profile, so that adds nothing. The description contributes no behavioral context beyond a REST path: nothing about default sort order, page-size default behavior, what the response contains, or whether filters combine with AND semantics — all of which matter for a paginated filtered list.

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, front-loaded with the actual behavior, with no filler. The trailing API path is slightly redundant but tiny and potentially useful for correlating with API docs.

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 8 parameters, pagination, and filters but no output schema, the description should at least sketch what comes back (task summaries with cursor-based paging) or note that the filters are combinable. It does not, leaving the schema to carry the load — adequate but thin for an endpoint of this surface area.

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 75%, so several parameters (cursor, page_size, project_id, status_ids, assignee_ids, incomplete_only) are already documented in the schema. The description adds nothing to those, and sort_by/sort_order carry enum values but no explanatory text in either place. Baseline 3 for a mostly-covered 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 and resource with scope attached ('List the tasks of one project'), which cleanly separates it from gorelo_list_projects and from the ticket/client list tools. It stops short of explicitly differentiating itself from sibling list endpoints, but the resource is unambiguous.

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

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

There is no when-to-use guidance, no mention of alternatives for cross-project task listing, and no note that project_id comes from gorelo_list_projects (that hint lives only in the schema). The REST endpoint reference ('GET /v1/projects/{projectId}/tasks') does not help an agent decide when to call it.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description's burden is reduced. It adds the endpoint and the fact that both public and private comment kinds are returned, but says nothing about pagination behavior, ordering defaults, or permissions needed to see private notes.

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 purpose and followed by the concrete endpoint. Nothing is redundant 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?

For a read-only paginated list tool with a well-described 6-parameter schema and no output schema, this is close to sufficient. The remaining gap is the missing default ordering for sort_order and any hint about what a comment object contains.

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 83%, so the schema already explains cursor, page_size, ticket_id, and both conversation filters. The description adds no parameter-level meaning, and the one undocumented parameter (sort_order) is left without a default or ordering semantics in either place.

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 ("List the comments ... on a ticket") and clarifies the resource subtypes (public replies, private notes), which lets an agent separate it from gorelo_add_ticket_comment and gorelo_get_ticket. It stops short of explicitly naming an alternative, but the operation is unambiguous.

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

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

There is no statement of when to use this tool versus alternatives such as gorelo_get_ticket (which may already include comments) or the list_* siblings, and no exclusions or prerequisites. The API endpoint line is implementation detail, not usage 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?

The readOnlyHint annotation already tells the agent this is a safe, non-mutating read, so the description does not need to restate safety. It adds the underlying endpoint (GET /v1/tickets/priorities), which is mildly useful for debugging, but says nothing about the response shape or whether priorities are workspace-scoped, which matters since there is no output schema.

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

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

Two short sentences with the action front-loaded and no filler. The trailing API-endpoint sentence is marginally useful rather than wasteful, though it could be dropped without loss for a calling agent.

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

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

For a zero-parameter read tool this is close to adequate, but with no output schema the agent still does not know what a priority record contains (id, name, ordering) or whether the list is global or tenant-scoped. One clause covering that would complete the definition.

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. The description correctly implies no filtering or pagination inputs are needed.

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

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

The description states a specific verb and resource ("List the ticket priorities"), making the operation unambiguous. It does not differentiate from near-siblings like gorelo_list_ticket_statuses or gorelo_list_ticket_types, so an agent must rely on the tool name alone to choose among them.

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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to the sibling list tools (statuses, types) that serve a similar lookup role. Usage is only inferable from the name.

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?

readOnlyHint=true already covers the safety profile, and the description adds gain beyond that: the default sort direction and the exact fields returned, which matters because there is no output schema. It says nothing about permissions or result volume limits, but the behavioral core is disclosed.

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-loading what is listed and in what order, then the id-resolution guidance and endpoint. No filler or restatement of the title.

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

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

For an 18-parameter read-only list tool with no output schema, the description covers what comes back, default ordering, and how to source the id filters. Sort/paging knobs are fully specified in the schema, so the remaining gap is minor.

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 89% schema description coverage the schema does most of the work, but the description adds meaning the schema does not: that status/type/priority ids must first be obtained from sibling lookup tools. The comma-separated id convention and timestamp semantics are left to the schema, which 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 ('List service tickets'), the default ordering ('newest activity first'), the fields surfaced ('status, priority, client, assignees and SLA'), and the backing endpoint. An agent can distinguish this from gorelo_get_ticket and gorelo_list_ticket_comments 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?

Explicitly routes the agent to gorelo_list_ticket_statuses/types/priorities to resolve filter ids, which is real conditional guidance. It stops short of naming exclusions, e.g. that gorelo_get_ticket should be used when a single ticket is already known, so it is clear but not fully comparative.

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 the description adds useful context beyond that: it returns only id and name, and it hits GET /v1/tickets/statuses. Since there is no output schema, disclosing the returned fields is a meaningful transparency contribution.

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?

One front-loaded sentence plus a compact API reference. Every element earns its place, with no filler or repetition of the title.

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

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

For a zero-parameter, read-only list tool, the description covers purpose, return fields, and endpoint. The absence of ordering or pagination notes is a minor gap but not material for a small status lookup.

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 are zero parameters and the schema is empty, so the baseline is 4. No parameter explanation is needed, and the description adds no misleading parameter claims.

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 (ticket statuses), and adds the return shape '(id and name)' plus a use case (filter or update tickets). That makes it clearly identifiable against siblings like gorelo_list_ticket_priorities or gorelo_list_ticket_types, though it doesn't explicitly name those alternatives.

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

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

The phrase 'used to filter or update tickets' implies context for calling it, but there is no explicit when-to-use/when-not guidance, no mention of prerequisites, and no named alternative tool. Usage is implied but not fully guided.

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

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

readOnlyHint=true already establishes this as a safe read, so the burden is lower. The description adds only the HTTP endpoint, which is not behaviorally useful to an agent; it says nothing about whether the list is complete, paginated, or scoped to the account.

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 with the purpose front-loaded and no filler. The endpoint sentence adds little for an agent but is harmless and brief.

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 trivial zero-param read with a readOnly annotation and no output schema, this is minimally adequate. However, the agent is not told what a ticket type contains (e.g. id/name) or how to use the result downstream, so the description is thin even for a simple tool.

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 the description needed to disambiguate. The description correctly implies a no-argument, unfiltered listing.

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 ticket types), which is unambiguous against siblings like list_ticket_priorities or list_ticket_statuses. It does not explicitly differentiate itself from those near-identical siblings beyond the noun, but the resource name is precise enough to select it.

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?

There is no guidance on when to call this, e.g. to resolve a valid type ID before gorelo_create_ticket or gorelo_update_ticket. No alternatives or exclusions are named, leaving the agent to infer usage entirely from the tool name.

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?

readOnlyHint=true already declares the safety profile, so the description only needs to add context such as pagination behavior, default ordering, or how filters interact — none of which it provides. The only added information is the REST endpoint, which is of marginal use to an agent selecting a tool.

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 with the purpose front-loaded and no filler. The trailing 'API: GET /v1/time-entries' is arguably redundant for tool selection but is cheap and occasionally useful for cross-referencing documentation.

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 nine optional filters, cursor pagination, and no output schema, the description leaves the agent to infer how filters combine, what the default ordering is, and what a page of results contains. The schema carries the parameter burden, but the overall definition is only minimally adequate for a multi-filter list endpoint.

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

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

Schema description coverage is 100%, and each of the nine parameters is documented in the schema with format examples (comma-separated ids, ISO-8601 timestamps, page_size 1-200). The description adds no semantics beyond that, 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 ('List logged time') plus the scope it spans ('across tickets and tasks'), so an agent knows it returns time-entry records rather than tickets or tasks themselves. It does not explicitly contrast with the sibling write tool gorelo_log_time_entry or with gorelo_list_project_tasks, but the verb+resource is unambiguous.

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

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

There is no statement of when to use this tool versus alternatives, no mention of prerequisites, and no guidance on how the filters are meant to be combined. The agent must infer everything from the parameter names.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the endpoint and that records carry role and status, which is modest extra context, but says nothing about pagination behavior, result volume, or permissions beyond what the schema's cursor/page_size fields imply.

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?

A single compact line that front-loads the identity of the resource, then the practical purpose, then the endpoint. No filler or redundancy.

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

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

For a zero-required-parameter read-only list tool with fully described params and an annotation covering safety, this is close to sufficient; 'use their ids' implicitly signals that ids are returned. The absence of any statement about result fields or pagination flow (cursor returned as DataContext.Pagination.NextCursor, only documented in the schema) is a small 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 query, cursor, group_ids, status_ids and page_size are fully documented in the schema. The description adds no filter syntax or format details beyond alluding to role and status, so 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 ('List users (technicians)') and reveals the underlying endpoint (GET /v1/organization/users), which pins down the resource among many list_* siblings. It does not explicitly contrast with gorelo_list_contacts or gorelo_list_clients, but 'technicians' is a clear enough resource distinction.

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

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

The phrase 'use their ids as assignee ids' hints at why an agent would call this (to resolve assignees before creating or updating a ticket), but there is no explicit when-to-use / when-not guidance and no named alternative. Usage is implied rather than instructed.

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

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

Beyond the destructiveHint annotation, it discloses non-obvious behavior: the API derives the missing third time field, billing role/work type/billable status are inherited from the ticket rather than supplied, and retrying after an unclear error risks duplicate entries. That duplicate-write hazard is exactly the operational risk an agent needs to know before calling a write tool.

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

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

Four short sentences, front-loaded with the "WRITE:" marker and the resource, then the invocation rule, then defaults, then the retry hazard, then the endpoint. Nothing is redundant with the schema or title.

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 8 params, 100% schema coverage and no output schema, the description covers the risky parts (field derivation, inherited defaults, duplicate risk). It does not say what a successful call returns, which matters somewhat given there is no output schema to fall back on.

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 field meaning is already documented; the baseline would be 3. The description earns above baseline by adding a cross-parameter rule absent from the schema: required is 0, yet exactly two of started_on/ended_on/actual_hours must be supplied and the API computes the third. It does not explain user_id defaulting or billable_status_id fallback behavior in any more detail than 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?

"WRITE: log work time against a ticket (or a project task)" gives a specific verb, resource and the two valid targets, and the API line names the exact endpoint. This is clearly distinguishable from gorelo_list_time_entries and the other read/create siblings.

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

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

It states the operational constraint for invocation (any two of started_on, ended_on, actual_hours) and a clear when-not ("Do not retry after an unclear error"). It never names an alternative sibling, e.g. checking gorelo_list_time_entries to confirm whether an ambiguous submission landed, so it stops short of full routing guidance.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description reinforces the write nature with a 'WRITE:' prefix. It adds genuinely non-annotated behavior: the change propagates to the alert's whole stack, and the underlying PATCH endpoint. It does not cover auth/permission needs or what happens to an existing ticket link on restore.

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 leading 'WRITE:' flag and the enumerated actions are front-loaded, followed by the stack-scope caveat and endpoint. 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 3-parameter mutation with no output schema, it covers the state model, the conditional parameter, and blast radius. A minor gap remains around what occurs to an existing ticket association when restoring an alert to New, and whether the response confirms the new state.

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 67% with alert_id and ticket_id documented there, but the description adds real meaning for the status value — mapping 'dismissed' to dismiss, 'new' to restore, and 'ticketed' to linking a ticket, plus the conditional requirement for ticket_id. That exceeds the bare enum in 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 names a specific verb set and resource — dismiss/restore/link an alert — and enumerates the three allowed state transitions that match the status enum. An agent can immediately distinguish this from read siblings like gorelo_get_alert and gorelo_list_alerts.

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 a concrete conditional rule ('status ticketed needs ticket_id') and scope guidance ('applies to the alert's whole stack, as in the app'), which is clear usage context. It stops short of naming alternatives or when-not-to-use cases (e.g., read the alert first with gorelo_get_alert).

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?

Adds substantial context beyond the annotations: the destructive behavior is made concrete ('Changing the client clears the ticket's contact and assets'), and side effects are disclosed ('Each change notifies and logs as in the app'). The PATCH endpoint is given, which corroborates the idempotentHint and confirms the partial-update model that destructiveHint alone 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?

Three tight sentences with the mutation marker and field list front-loaded, followed by the update semantics and the one genuinely dangerous side effect. Nothing is repeated from the schema and every sentence carries decision-relevant 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 9-parameter mutation with no output schema, the description covers mutation intent, partial-update behavior, side effects and the cascade consequence — enough to call it safely. It stops short of stating what the call returns or any permission/rate-limit requirements, which a write tool of this complexity would ideally include.

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 only 33%, so the description must compensate and does so partially — it lists status, priority, assignee, title and tags, and explains the client_id cascade. It leaves type_id, contact_id and the id-typed fields unexplained, and 'tag_ids' semantics live only in the schema, so coverage remains incomplete.

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 'WRITE: change fields of a ticket' — a specific verb plus resource — and enumerates the mutable fields (status, priority, assignee, title, tags). The write/mutation nature is signposted clearly against a sibling set dominated by get_/list_ tools, though it never names the adjacent create_ticket or add_ticket_comment to draw the boundary.

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?

'Only the fields you send change' communicates partial-update semantics and implies this is the tool for modifying an existing ticket rather than creating one. However, there is no explicit when-not guidance and no named alternative, so an agent must infer that comments belong to gorelo_add_ticket_comment and new tickets to gorelo_create_ticket.

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